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

Last modified: Sat Jul 26 18:17:38 2025.

# Directory Listing of Routines

# projects/maven/swea

- BINDATA
  Bins a 2D data set and calculates moments for each bin: mean, standard
- BINDATA2D
  Bins a 3D data set and calculates moments for each bin: mean, standard
- CTIME2[1]
  A version of ctime. May become obsolete.
- CTIME_GET_EXACT_DATA2
- CTIME2[2]
  Interactively uses the cursor to select a time (or times)
- FIT_PAD_MAG
  Determines the time offset between MAG1 data and SWEA MAG angles. For SWEA pitch
- MAV_PFDPU_PART_DECOMPRESS_DATA2
  Decompresses ESA science packets (SWEA/SWIA/STATIC). If the packet is already
- MVN_LPW_LOAD_DLM
  For a given UTC date, routine will check if the orbit data is present on the local machine. If not, it will download that data from the Berkeley server.
- MVN_MAG_TPLOT
  Makes fancy MAG tplot panels: amplitude on a log scale, and phi/theta
- MVN_SC_RAMDIR
  Determines the spacecraft orbital velocity vector relative to
- MVN_STA_CIO_CLEAR
  Clears pointers to free the memory used by heap variable(s).
- MVN_STA_CIO_CONVERT
  Converts array-of-structures to structure-of-arrays. Also performs
- MVN_STA_CIO_FILTER
  A tag 'filter' is added to the input data structure. This tag holds
- MVN_STA_CIO_LOAD
  Loads all available MAVEN cold ion outflow data that were
- MVN_STA_CIO_PLOT
- MVN_STA_CIO_RESTORE
  Restores STATIC cold ion outflow results.
- MVN_STA_CIO_SAVE
  Saves STATIC cold ion outflow results in save/restore files.
- MVN_STA_CIO_SNAP
  Makes plots of statistics within individual pixels in maps created with
- MVN_STA_CIO_STRUCT
  Creates a Cold Ion Outflow data structure.
- MVN_STA_CIO_TPLOT
- MVN_STA_CIO_UPDATE
  Updates STATIC cold ion outflow results in save/restore files.
- MVN_STA_COLDION
  Loads STATIC data and calculates density, temperature, and velocity of
- MVN_SWE_3DSUM
  Sums multiple 3D data structures. This is done by summing raw counts
- MVN_SWE_ADDEUV
  Loads EUV data and creates tplot variable using EUV code. EUV is
- MVN_SWE_ADDLPW
  Loads LPW data and creates tplot variables using LPW code.
- MVN_SWE_ADDMAG
  Loads MAG data from L2 or L1 save/restore files, rotates the MAG vectors to
- MVN_SWE_ADDPOT
- MVN_SWE_ADDSEP
  Loads SEP data, sums over the look directions, and stores electron and ion
- MVN_SWE_ADDSTA
  Loads STATIC data and creates tplot variables using STATIC code.
- MVN_SWE_ADDSWI
  Loads SWIA data and calculates moments based on coarse survey. All calculations
- MVN_SWE_BACKGROUND
  At energies above ~1 keV, the SWEA count rate comes from three
- MVN_SWE_CALC_SHAPE_ARR
  Take an input spectrum and calculate the shape parameter
- MVN_SWE_CALIB
  Maintains SWEA calibration factors in a common block (mvn_swe_com).
- MVN_SWE_CATALOG
  Looks in the SWEA L2 data directories and builds a catalog of files
- MVN_SWE_CLEAR
  Clears the swe_dat common block.
- MVN_SWE_COM
  Stores the SWEA static memory.
- MVN_SWE_CONFIG
  Maintains SWEA configuration changes in a common block (mvn_swe_com).
- MVN_SWE_CONVERT_QUALITY
  Converts olde format quality database into new format.
- MVN_SWE_CONVERT_UNITS
  Convert units for SPEC, PAD, and 3D data.
- MVN_SWE_CRIB
- MVN_SWE_CROSSCAL
  Calculates SWEA-SWIA cross calibration factor as a function of time.
- MVN_SWE_D2F_HEII
  To calculate second derivatives of energy flux, used in routine
- MVN_SWE_EDIT_QUALITY
  Interactively edit the quality flags by using the cursor and
- MVN_SWE_EPARAM
  Calculates the gyrofrequency, gyroradius and adiabatic condition
- MVN_SWE_ESUPPRESS
  Calculates the SWEA electron suppression constant (Ke). The correction is
- MVN_SWE_ETSPEC
  Makes tplot variables with respect to the MAVEN SWEA
- MVN_SWE_FLATFIELD
  Maintains the angular sensitivity calibration and provides a means to
- MVN_SWE_FLATFIELD_TEST
- MVN_SWE_FOVCAL
  Given 3D electron distributions, the magnetic field direction, the
- MVN_SWE_FOVMAP
  Calculates the SWEA FOV in the form of an array of unit vectors pointing to each
- MVN_SWE_FOVPLOT
  Plots the results of a FOV calibration obtained with mvn_swe_fovcal.
- MVN_SWE_GET3D
  Returns a SWEA 3D data structure constructed from L0 data or extracted
- MVN_SWE_GETBITS
  Extracts a sub-word defined by a range of bits from an input word.
- MVN_SWE_GETLUT
  Determines the sweep lookup table used for each 2-sec measurement
- MVN_SWE_GETPAD
  Returns a SWEA PAD data structure constructed from L0 data or extracted
- MVN_SWE_GETSPEC
  Returns a SWEA SPEC data structure constructed from L0 data or extracted
- MVN_SWE_HSKPLOT
  Plots time series summary plots of SWEA housekeeping data over arbitrarily
- MVN_SWE_INIT
  Initializes SWEA common block (mvn_swe_com).
- MVN_SWE_KP
  Calculates SWEA key parameters. The result is stored in tplot variables,
- MVN_SWE_LOAD_HSK
  Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
- MVN_SWE_LOAD_L0
  Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
- MVN_SWE_LOAD_L2
  Reads in MAVEN SWEA Level 2 telemetry files (CDF format). Data are stored in
- MVN_SWE_LOWE_MASK
  Masks data affected by the sporadic low energy suppression anomaly. The affected spectra
- MVN_SWE_LPW_SCPOT
- MVN_SWE_LPW_SCPOT_RESTORE
  Reads in scpot data precalculated by mvn_swe_lpw_scpot
- MVN_SWE_LPW_SCPOT_SAVE
- MVN_SWE_MAGDIR
  Converts magnetic field azimuth and elevation bytes from PAD packets
- MVN_SWE_MAKECDF_3D
  Routine to produce CDF file from SWEA 3D data structures
- MVN_SWE_MAKECDF_PAD
  Routine to produce CDF file from SWEA pad data structures
- MVN_SWE_MAKECDF_SPEC
  Routine to produce CDF file from SWEA spec data structures.
- MVN_SWE_MAKEFPAD
  Constructs Hires PAD data structures from raw data.
- MVN_SWE_MAKESPEC
  Constructs ENGY data structure from raw data.
- MVN_SWE_MCPCAL
  Analyzes in-flight MCP calibration data to estimate the optimal
- MVN_SWE_N1D
  Determines density and temperature moments from 1D energy spectra.
- MVN_SWE_N3D
  Determines density from a 3D distribution. Adapted from McFadden's n_3d.pro.
- MVN_SWE_PAD_LC_RESTORE
  Reads in save files mvn_swe_padscore
- MVN_SWE_PAD_RESAMPLE
  Resamples the pitch angle distribution from SWEA PAD or 3D data,
- MVN_SWE_PAD_RESTORE
  Reads in resampled pad data (100-150 eV) precalculated by mvn_swe_pad_resample
- MVN_SWE_PAD_SAVE
  Calculates resampled pad data (100-150 eV) using mvn_swe_pad_resample and
- MVN_SWE_PADLUT
  Calculates the pitch angle sorting look up table.
- MVN_SWE_PADMAP
  Calculates the pitch angle map for a PAD. See mvn_swe_fovmap for the
- MVN_SWE_PADMAP_32HZ
- MVN_SWE_PADMAP_3D
  Map pitch angle for PAD or 3D distributions. In either case, you must first
- MVN_SWE_PADSUM
  Sums multiple PAD data structures. This is done by summing raw counts
- MVN_SWE_POT_CONVE
  correct for potential and then convert to SWEA original resolution
- MVN_SWE_QL
  Creates SWEA TPLOT variables for QuickLook plots.
- MVN_SWE_READ_HSK
  Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
- MVN_SWE_READ_L0
  Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
- MVN_SWE_READCDF_3D
  Routine to read CDF file from mvn_swe_makecdf_3d.pro
- MVN_SWE_READCDF_PAD
  Routine to read CDF file from mvn_swe_makecdf_pad.pro
- MVN_SWE_READCDF_SPEC
  Routine to read CDF file from mvn_swe_makecdf_spec.pro
- MVN_SWE_REGID_RESTORE
  Reads in save files mvn_swia_regid
- MVN_SWE_RESTORE
  Restores SWEA save files and updates the SWEA common blocks.
- MVN_SWE_SAVE
  Saves the SWEA common block to a save file.
- MVN_SWE_SC_NEGPOT
  Estimates the negative spacecraft potential within the ionosphere
- MVN_SWE_SC_NEGPOT_TWODIR_BURST
  Estimates potentials from the shift of He II features
- MVN_SWE_SC_POSPOT
  Estimates the spacecraft potential from SWEA energy spectra. The basic
- MVN_SWE_SC_POT
  Estimates the spacecraft potential from SWEA energy spectra. The basic
- MVN_SWE_SCIPLOT
  Creates a science-oriented summary plot for SWEA and MAG and optionally other
- MVN_SWE_SECONDARY
  Estimates contamination caused by secondary electrons emitted from interior
- MVN_SWE_SET_QUALITY
  Inspects SPEC, PAD and 3D data (survey and burst) in the common block.
- MVN_SWE_SHAPE_DAILYSAVE
- MVN_SWE_SHAPE_PAR
  Calculates SWEA energy shape parameter and stores it as a TPLOT variable.
- MVN_SWE_SHAPE_PAR_PAD
- MVN_SWE_SHAPE_PAR_PAD_L2
- MVN_SWE_SHAPE_PAR_PAD_RESTORE
  Reads in tplot save/restore files swe_shape_par_pad
- MVN_SWE_SHAPE_RESTORE
  Reads in save files swe_shape_par_pad
- MVN_SWE_SLICE2D_SNAP
- MVN_SWE_SPECPLOT
  Plots time series summary plots of SWEA SPEC data over arbitrarily long
- MVN_SWE_SPECSUM
  Sums multiple SPEC data structures. This is done by summing raw counts
- MVN_SWE_SPICE_INIT
  Initializes SPICE.
- MVN_SWE_STAT
  Reports the status of SWEA data loaded into the common block.
- MVN_SWE_STRUCT
  Defines data structures for 3D, PAD, and ENGY products. These work for both survey
- MVN_SWE_SUMPLOT
  Plots information generated by MAVEN SWEA APID's.
- MVN_SWE_SUNDIR
  Calculates the direction of the Sun in SWEA coordinates.
- MVN_SWE_SWEEP
  Generates a SWEA sweep table exactly as done in flight software (same digital
- MVN_SWE_SWI_CAL
  Compares ion density from SWIA and electron density from SWEA for the purpose
- MVN_SWE_TABNUM
  Given a checksum, determines the corresponding table number. Only returns
- MVN_SWE_VALIDLUT
  Checks for valid sweep lookup tables (LUTs). The valid
- MVN_SWE_VERBOSE
  Sets the SWEA verbosity level.
- NIBBLE
  Converts a byte, integer, long, or long64 into an N-element
- NIBBLE_LONG
  Converts an unsigned long into a 32-element byte array where the
- NIBBLE_WORD
  Converts an unsigned int into a 16-element byte array where the
- ROTATE_MAG_TO_SWE
  Rotates input vectors from MAG instrument coordinates to
- SIGFIG
  Simple function for rounding off.
- SWE_3D_SNAP
  Plots 3D snapshots in a separate window for times selected with the cursor in
- SWE_3D_STITCH
  Constructs 3D spectra from A0 and A1 packets. Depending on the group parameter,
- SWE_3D_STRAHL_DIR
  Determines the direction in SWEA coordinates of the strahl.
- SWE_3D_TIMING
  Disassembles A0 packets and sorts data in time sequence.
- SWE_A0_SNAP
  Plots 3D snapshots in a separate window for times selected with the cursor in
- SWE_A2_SNAP
  Plots PAD snapshots in a separate window for times selected with the cursor in
- SWE_A4_SNAP
  Plots SPEC snapshots in a separate window for times selected with the cursor in
- SWE_CAL_SNAP
  Plots snapshots of calibration data in a separate window for times selected
- SWE_DEADTIME
  Calculates the deadtime correction given the measured count rate and the
- SWE_ENGY_SNAP
  Plots omnidirectional energy spectrum snapshots in a separate window for times
- SWE_ENGY_TIMING
  Disassembles A4 packets and sorts data in time sequence.
- SWE_GETMAG_QL
  Loads MAG data from one of two sources:
- SWE_HSK_SNAP
  Plots housekeeping snapshots for times selected with the cursor in a tplot
- SWE_LOWE_CLUSTER
  Sporadic low-energy anomaly cluster analysis.
- SWE_MAKE_HIRES
  Loads L0 data containing hires SWEA data (LUT = 7,8,9) and 32-Hz MAG data,
- SWE_MAXBOL
  Maxwell-Boltzmann distribution for fitting SWEA electron energy spectra.
- SWE_N_3D
  Returns the density, n, 1/cm^3
- SWE_PAD32HZ_UNPACK
  Expands a high time resolution PAD structure into 64 single-energy
- SWE_PAD_SNAP
  Plots PAD snapshots in a separate window for times selected with the cursor in
- SWE_PAD_TIMING
  Disassembles A2 packets and sorts data in time sequence.
- SWE_PLOT_FHSK
  Makes tplot variables for SWEA fast housekeeping data (A6).
- SWE_ROTATE
  Rotates SWEA 3D or PAD look directions into any valid SPICE frame.
- SWE_SHAPE_PAR_PAD_L2_3PA
- SWE_SNAP_COMMON
  Common block for swe_snap_layout.
- SWE_SNAP_LAYOUT
  Puts snapshot windows in convenient, non-overlapping locations,
- SWE_SNAP_OPTIONS
  Stores a structure of SWEA snapshot keyword options and provides
- SWE_SWI_CC_SNAP
  Gets cross calibration factor from SWE-SWI density ratio.
- SWE_TESTPULSER_MODEL
  Creates SWEA Test Pulser Model and generates test pulser signatures
- SWEICC
  Performs SWEA-SWIA cross calibration. This is only intended for the
- SWEICCD
  Performs SWEA-SWIA cross calibration. This is the companion routine
- TIMEFIT
  Given an input time array or tplot variable name, sets the tplot time window to span
- TOPOMTRX

# Routine Descriptions

## BINDATA

[Next Routine] [List of Routines]

    PROCEDURE:   bindata
    PURPOSE:
      Bins a 2D data set and calculates moments for each bin: mean, standard
      deviation, skewness, kurtosis, and mean absolute deviation.  Also
      determines the median, upper quartile, lower quartile, minimum, and
      maximum.

        skewness: = 0 -> distribution is symmetric about the maximum
                  < 0 -> distribution is skewed to the left
                  > 0 -> distribution is skewed to the right

        kurtosis: = 0 -> distribution is peaked like a Gaussian
                  < 0 -> distribution is less peaked than a Gaussian
                  > 0 -> distribution is more peaked than a Gaussian

    USAGE:
      bindata, x, y
    INPUTS:
           x:         The independent variable.

           y:         The dependent variable.  If any elements of y are not
                      finite, they are treated as missing data.  They are
                      not included when calculating statistics, and they are
                      not included in the distribution (see keyword DST below).

    KEYWORDS:
           XBINS:     The number of bins to divide x into.  Takes precedence
                      over the DX keyword.

           DX:        The bin size.

           XRANGE:    The range for creating bins.  Default is [min(x),max(x)].

           RESULT:    A structure containing the moments, median, quartiles,
                      minimum, maximum, and the number of points per bin.

           DST:       Stores the distribution for each bin.  Can take a lot of
                      space but allows detailed inspection of statistics.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-03 11:49:42 -0700 (Tue, 03 Jun 2025) $
     $LastChangedRevision: 33358 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/bindata.pro $

    CREATED BY:	David L. Mitchell

(See projects/maven/swea/bindata.pro)

## BINDATA2D

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

    PROCEDURE:   bindata2d
    PURPOSE:
      Bins a 3D data set and calculates moments for each bin: mean, standard
      deviation, skewness, kurtosis, and mean absolute deviation.  Also
      determines the median, upper quartile, lower quartile, minimum, and
      maximum.

        skewness: = 0 -> distribution is symmetric about the maximum
                  < 0 -> distribution is skewed to the left
                  > 0 -> distribution is skewed to the right

        kurtosis: = 0 -> distribution is peaked like a Gaussian
                  < 0 -> distribution is less peaked than a Gaussian
                  > 0 -> distribution is more peaked than a Gaussian

    USAGE:
      bindata2d, x, y, z
    INPUTS:
           x:         The first independent variable (N-element array).

           y:         The second independent variable (M-element array).

           z:         The dependent variable (N x M array).  If any elements
                      of z are not finite, they are treated as missing data.
                      They are not included when calculating statistics, and
                      they are not included in the distribution (see keyword
                      DST below).

    KEYWORDS:
           XBINS:     The number of bins to divide x into.  Takes precedence
                      over the DX keyword.

           DX:        The X bin size.

           XRANGE:    The range for creating bins.  Default is [min(x),max(x)].

           YBINS:     The number of bins to divide y into.  Takes precedence
                      over the DY keyword.

           DY:        The Y bin size.

           YRANGE:    The range for creating bins.  Default is [min(y),max(y)].

           RESULT:    A structure containing the moments, median, quartiles,
                      minimum, maximum, and the number of points per bin.

           DST:       Stores the distribution for each bin.  Can take a lot of
                      space.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-05 08:10:18 -0700 (Thu, 05 Jun 2025) $
     $LastChangedRevision: 33369 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/bindata2d.pro $

    CREATED BY:	David L. Mitchell

(See projects/maven/swea/bindata2d.pro)

## CTIME2[1]

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

    PROCEDURE:   ctime2
    PURPOSE:
      A version of ctime.  May become obsolete.

     $LastChangedBy: jimm $
     $LastChangedDate: 2017-02-27 13:15:35 -0800 (Mon, 27 Feb 2017) $
     $LastChangedRevision: 22870 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/ctime2.pro $

    CREATED BY:	David L. Mitchell  2013-07-26
    FILE:  ctime2.pro

(See projects/maven/swea/ctime2.pro)

## CTIME2[2]

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

    PROCEDURE:   ctime2,time,y,z
    INPUT:
        time: Named variable in which to return the selected time (seconds
              since 1970)
        y:    Named variable in which to return the y value
        z:    Named variable in which to return the z value
    KEYWORDS:
        PROMPT:  Optional prompt string
        NPOINTS: Max number of points to return
        PSYM:    If set to a psym number, the cooresponding psym is plotted at
                 selected points
        SILENT:  Do not print data point information
        PANEL:   Set to a named variable to return an array of tplot panel numbers
                 coresponding to the variables points were chosen from.
        APPEND:  If set, points are appended to the input arrays,
                 instead of overwriting the old values.
        VNAME:   Set to a named variable to return an array of tplot variable names,
                 cooresponding to the variables points were chosen from.
        COLOR:   An alternative color for the crosshairs.  0<=color<=!d.n_colors-1
        SLEEP:   Sleep time (seconds) between polling the cursor for events.
                 Defaults to 0.1 seconds.  Increasing SLEEP will slow ctime down,
                 but will prevent ctime from monopolizing cpu time.
        INDS:    Return the indices into the data arrays for the points nearest the
                 recorded times to this named variable.
        VINDS:   Return the second dimension of the v or y array.
                 Thus  TIME(i) is  data.x(INDS(i))           and
                       Y(i)    is  data.y(INDS(i),VINDS(i))  and
                       V(i)    is  data.v(VINDS(i)) or data.v(INDS(i),VINDS(i))
                 for get_data,VNAME(i),data=data,INDS=INDS,VINDS=VINDS
        EXACT:   Get the time,y, and (if applicable) z values from the data
                 arrays.  If on a multi-line plot, get the value from the line
                 closest to the cursor along y.
        NOSHOW:  Do not show the plot window.
        DEBUG:   Avoids default error handling.  Useful for debugging.
        DAYS, HOURS, MINUTES, SECONDS: Sets time granularity.  For example
                 with MINUTES=1, CTIME will find nearest minute to cursor
                 position.

        BUTTON:  Returns the last button pressed.
    PURPOSE:
       Interactively uses the cursor to select a time (or times)
    NOTES:	      If you use the keyword EXACT, ctime may run noticeablly slower.
    	      Reduce the number of time you cross panels, especially with
    	      tplots of large data sets.
    SEE ALSO:  "crosshairs"

    CREATED BY:	Davin Larson & Frank Marcoline
    LAST MODIFICATION:     @(#)ctime.pro	1.40 99/04/22
    WARNING!
      If ctime crashes, you may need to call:
      IDL> device,set_graph=3,/cursor_crosshair

(See projects/maven/swea/ctime2.pro)

## CTIME_GET_EXACT_DATA2

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

    NAME:
       ctime_get_exact_data2
    PROCEDURE:     ctime_get_exact_data2
    PURPOSE:       Get a data structure for ctime.  if var is a string or a strarr,
                   create a structure of data structures.
                   Get the new values for hx and hy, the crosshairs position.
                   Also check the spec option.
                   ctime need never see the actual data structures.
    		All work is done with pointers to reduce data duplication
                   and increase speed.
    COMMON BLOCKS: CTIME_COMMON
    HISTORY:       First appeared in ctime version 1.29

(See projects/maven/swea/ctime2.pro)

## FIT_PAD_MAG

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

    PROCEDURE:   fit_pad_mag
    PURPOSE:
      Determines the time offset between MAG1 data and SWEA MAG angles.  For SWEA pitch
      angle sorting, the magnetic field is averaged over the second half of the 2-sec
      measurement cycle.  However, there can be apparent differences between the MAG and
      SWEA timing if one of the decommutators has an error.  Here, I assume that the SWEA
      timing is correct (naturally) and fit for a constant MAG time offset.

    USAGE:
      fit_pad_mag

    INPUTS:

    KEYWORDS:
           RESULT:       Timing and angular offsets.  The timing offset is robust.
                         Angular offsets are for reference only.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2015-02-04 13:44:34 -0800 (Wed, 04 Feb 2015) $
     $LastChangedRevision: 16867 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/fit_pad_mag.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/fit_pad_mag.pro)

## MAV_PFDPU_PART_DECOMPRESS_DATA2

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

    FUNCTION:   mav_pfdpu_part_decompress_data2
    PURPOSE:
      Decompresses ESA science packets (SWEA/SWIA/STATIC).  If the packet is already
      uncompressed, it is simply returned unchanged.

    USAGE:
      decompressed_pkt = mav_pfdpu_part_decompress_data2(compressed_pkt)

    INPUTS:
           compressed_pkt:  ESA science packet that is possibly compressed.

    KEYWORDS:

     $LastChangedBy: jimm $
     $LastChangedDate: 2015-03-22 14:24:35 -0700 (Sun, 22 Mar 2015) $
     $LastChangedRevision: 17163 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mav_pfdpu_part_decompress_data2.pro $

    CREATED BY:    David L. Mitchell  04-25-13
    FILE: mav_pfdpu_part_decompress_data2.pro

(See projects/maven/swea/mav_pfdpu_part_decompress_data2.pro)

## MVN_LPW_LOAD_DLM

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

    PROCEDURE:   mvn_lpw_load
    PURPOSE:
     For a given UTC date, routine will check if the orbit data is present on the local machine. If not, it will download that data from the Berkeley server.
     Routine will then find the kernels required for that orbit on your machine. If they are not present, they will also be downloaded from the Berkeley server.
     For now, routine grabs all SPICE kernels.
     Directories of the data file and required SPICe kernels are saved into tplot variables so they can be accessed by other routines.
     Routine can only take one utc date, as our load routines only do one orbit at a time.

    USAGE:
     mvn_lpw_load, '2014-02-02'
     mvn_lpw_load, filetype='GROUND'
     mvn_lpw_load, '2014-02-02', packet=['EUV','HSK'], tplot_var='all'

    INPUTS:

(See projects/maven/swea/mvn_lpw_load_dlm.pro)

## MVN_MAG_TPLOT

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

    PROCEDURE:   mvn_mag_tplot
    PURPOSE:
      Makes fancy MAG tplot panels: amplitude on a log scale, and phi/theta
      in a single panel.  This routine is not intended for general use, but
      you're welcome to use it.  Much of this code was borrowed from Takuya
      Hara.

    USAGE:
      mvn_mag_tplot
    INPUTS:
           bvec:      Tplot variable name containing the magnetic field vectors.
                      Default = 'mvn_B_1sec_maven_mso'.

    KEYWORDS:
           SANG:      Archmedian spiral angle at Mars.  Default = 54 deg (for
                      a nominal 400-km/s solar wind velocity).  The phi/theta
                      panel will contain horizontal lines at the angles for
                      toward and away sectors.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-09-05 08:53:38 -0700 (Tue, 05 Sep 2023) $
     $LastChangedRevision: 32078 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_mag_tplot.pro $

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

(See projects/maven/swea/mvn_mag_tplot.pro)

## MVN_SC_RAMDIR

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

    PROCEDURE:   mvn_sc_ramdir
    PURPOSE:
      Determines the spacecraft orbital velocity vector relative to
      the body-fixed rotating Mars frame (IAU_MARS).  The default is
      to rotate this vector into spacecraft coordinates.

      In the spacecraft frame, phi is the angle in the X-Y plane:
          0 --> +X axis (APP boom)
         90 --> +Y axis (+Y solar array and MAG1)
        180 --> -X axis
        270 --> -Y axis (-Y solar array and MAG2)

      and theta is the angle out of the X-Y plane:
        +90 --> +Z axis (HGA)
          0 --> X-Y plane
        -90 --> -Z axis

      In the APP frame, phi is the angle in the i-j plane:
          0 --> +i --> NGIMS boresight
        +90 --> +j --> IUVS fields of regard (general direction)

      and theta is the angle out of this plane:
        +90 --> +k --> STATIC symmetry direction

      This is the velocity vector -- the RAM flow is incident on the spacecraft
      from the opposite direction.

      The corotation 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 corotation 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.

    USAGE:
      mvn_sc_ramdir, trange

    INPUTS:
           trange:   Time range for calculating the RAM direction.

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

           FRAME:    Rotate to FRAME coordinates instead of Spacecraft coord.
                     Any frame defined in the MAVEN frames kernel is allowed.

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

           APP:      Shorthand for FRAME='MAVEN_APP'.

           PANS:     Named variable to hold the tplot variables created.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-03-18 16:09:56 -0700 (Sat, 18 Mar 2017) $
     $LastChangedRevision: 22985 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sc_ramdir.pro $

    CREATED BY:    David L. Mitchell  09/18/13

(See projects/maven/swea/mvn_sc_ramdir.pro)

## MVN_STA_CIO_CLEAR

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

    PROCEDURE:   mvn_sta_cio_clear
    PURPOSE:
      Clears pointers to free the memory used by heap variable(s).
      If a filter has been defined as part of the data structure,
      it is cleared too. Pointers from the feature structure and/or the
      plot-option structure are also cleared. Each input data is set to zero.

    USAGE:
      mvn_sta_cio_clear, ptr
    INPUTS:
           ptr    :    A pointer to heap variable(s) to be removed.

    KEYWORDS:
         feature  :    Structure generated by get_mars_features.pro.
         p_option :    Structure generated by create_iono_p_options.pro.
         filteronly :  Only remove the filter.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-05-01 12:23:32 -0700 (Fri, 01 May 2020) $
     $LastChangedRevision: 28655 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_clear.pro $

    CREATED BY:	David L. Mitchel
    FILE:  mvn_sta_cio_clear.pro

(See projects/maven/swea/mvn_sta_cio_clear.pro)

## MVN_STA_CIO_CONVERT

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

    PROCEDURE:   mvn_sta_cio_convert
    PURPOSE:
      Converts array-of-structures to structure-of-arrays.  Also performs
      several calculations and adds structure elements.

    INPUTS:
         data  : A named variable to hold the data.  Reformatted data are
                 returned in same variable.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-05-01 12:26:38 -0700 (Fri, 01 May 2020) $
     $LastChangedRevision: 28659 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_convert.pro $

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

(See projects/maven/swea/mvn_sta_cio_convert.pro)

## MVN_STA_CIO_FILTER

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

    PROCEDURE:   mvn_sta_cio_filter
    PURPOSE:
       A tag 'filter' is added to the input data structure.  This tag holds
       a pointer to a filter structure, which contains the filter definition
       and the indices of data that pass through the filter.  If a filter
       is already attached to the data structure then it will be overwritten
       with the new filter.

    USAGE:
      mvn_sta_cio_filter, ptr, filter

    INPUTS:
           ptr    :    A pointer to the CIO data structure.

           filter :    A structure containing allowed ranges for any of
                       the parameters, including time.  This structure can
                       have any combination of tags found in the CIO result
                       structure (see mvn_sta_cio_struct.pro).  Each tag
                       is given a range of values [min,max] that pass
                       through that component of the filter.  For example:

                         filter = {tag1 : [min1, max1] , $
                                   tag2 : [min2, max2] , $
                                     |          |
                                   tagN : [minN, maxN]    }

                       If a tag refers to an angle that wraps at 360 degrees,
                       then the filter is interpreted as follows:

                         tagN = [value1, value2]

                         If value1 < value2, then the filter passes angles
                         > value1 AND < value2.  If value1 > value2, then
                         the filter passes angles > value1 OR < value2.

                       If a tag is missing or set to 0, then no filter is
                       applied to that variable.  Only data that pass though
                       all the filters are used to calculate distributions.

                       The time range can be in any format accepted by
                       time_double().

    KEYWORDS:
           LIST   :    Print information about the filter, return
                       its value via the 'filter' input (if present).

           SUCCESS :   Returns 1 if there were no problems.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-14 10:13:15 -0700 (Mon, 14 Apr 2025) $
     $LastChangedRevision: 33261 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_filter.pro $

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

(See projects/maven/swea/mvn_sta_cio_filter.pro)

## MVN_STA_CIO_LOAD

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

    PROCEDURE:   mvn_sta_cio_load
    PURPOSE:
      Loads all available MAVEN cold ion outflow data that were
      processed by mvn_sta_coldion.pro.

    INPUTS:
         ptr   : A named variable to hold a pointer to the data.
      species  : Which database to load?  ('h', 'o1', 'o2')

    KEYWORDS:

        FROOT  : File root for save file (e.g., 'cio_ABCD_').

         TAGS  : A named variable to hold a string array of the names
                 of the data structure tags.

         NPTS  : A named variable to hold the number of data points.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-11-09 11:42:13 -0800 (Fri, 09 Nov 2018) $
     $LastChangedRevision: 26099 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_load.pro $

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

(See projects/maven/swea/mvn_sta_cio_load.pro)

## MVN_STA_CIO_PLOT

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

    PROCEDURE:   mvn_sta_cio_plot
    PURPOSE:

    USAGE:
      mvn_sta_cio_plot, ptr, KEYWORD=value, ...

    INPUTS:
           ptr:        A pointer to the cold ion data structure, which
                       is obtained with 'mvn_sta_cio_load'.

    KEYWORDS:
           OPTIONS:    Structure of options for selecting variables and binning
                       parameters.  Recognized options (tags) are:

               PVAR:       Parameter to plot.  Can be one of:

                             'den_i'  -> ion density
                             'den_e'  -> electron density
                             'temp'   -> ion temperature
                             'vbulk'  -> ion bulk velocity
                             'vratio' -> ratio of ion bulk velocity to escape velocity
                             'voratio' -> ratio of O2+ to O+ bulk velocity
                             'fbulk'  -> ion bulk flux (den_i * vbulk)
                             'vel_x'  -> ion velocity X component
                             'vel_y'  -> ion velocity Y component
                             'vel_z'  -> ion velocity Z component
                             'energy' -> ion bulk kinetic energy
                             'VB_phi' -> angle between V and B

               XVAR:       Parameter for the X variable.  Can be one of:

                             'time'  -> time               (UT/SCET)
                             'mso_x' -> MSO X              (Rm)
                             'mso_y' -> MSO Y              (Rm)
                             'mso_z' -> MSO Z              (Rm)
                             'mso_r' -> MSO R              (Rm)
                             'sza'   -> solar zenith angle (degrees)
                             'alt'   -> altitude           (km)
                             'slon'  -> subsolar longitude (degrees)
                             'slat'  -> subsolar latitude  (degrees)

               YVAR:       Parameter for the Y variable (see XVAR).  You must
                           specify at least one of XVAR and YVAR.  If only one
                           of these keywords is set, the binned PARAM is plotted
                           versus XVAR or YVAR.  If both are set, then a color
                           spectrogram of PVAR versus XVAR and YVAR is plotted.
                           YVAR cannot be 'time'.

               XBINS:      Number of bins for the X variable.  A reasonable
                           default based on XVAR is provided.

               YBINS:      Number of bins for the Y variable.  A reasonable
                           default based on YVAR is provided.

               XSPAN:      Range for binning the X variable.  A reasonable
                           default based on XVAR is provided.  This is not
                           the same as the X plot limits, which you specify
                           in the LIMITS keyword.

               YSPAN:      Range for binning the Y variable.  A reasonable
                           default based on YVAR is provided.  This is not
                           the same as the Y plot limits, which you specify
                           in the LIMITS keyword.

               STYPE:      Statistics to plot: 'mean' or 'median'.

               MTYPE:      Which moment to plot:
                             'sdev' : sdev/mean  (default)
                             'skew' : skewness
                             'kurt' : kurtosis
                             'adev' : adev/mean

               MINSAM:     Minimum number of samples per cell.  Cells that
                           contain fewer samples than this are not included
                           in the results.

               VVEC:       Overplots projections of the bulk velocity vectors in
                           the XVAR-YVAR plane.  Set this keyword to the scale
                           factor (Rm/km/s).  Only works when PVAR is set and
                           XVAR and YVAR are any two of MSO_X, MSO_Y, and MSO_Z.
                           Using this keyword with MSO_R (cylindrical coordinates)
                           is misleading!

               VSKIP:      Bin spacing between vectors in x and y directions.
                           Default = [1,1], i.e., every bin gets a vector.

               VBAR:       Three element array specifying the length (km/s), and
                           position (XVAR, YVAR) for a velocity scale bar.

           DATA:       A named variable to hold the average, median and
                       standard deviation of PARAM versus XVAR and/or YVAR.
                       The sampling (number of points per cell) is also
                       provided.  Finally, a copy of the filter definition
                       is included.

           DST:        Save the distributions for each bin in DATA.  Then use
                       mvn_sta_cio_snap to view them.

           DOPLOT:     Plot PVAR vs. XVAR and/or YVAR.
                       Set this keyword to the IDL window number where you
                       want the plot to appear (1 to 31).  The window size
                       is set to keep Mars round.

           DOSAMP:     Plot the sampling function vs. XVAR and/or YVAR.
                       Set this keyword to the IDL window number where you
                       want the plot to appear (1 to 31).  The window size
                       is set to keep Mars round.

           DOMOM:      Plot a moment of the distribution vs. XVAR and/or YVAR.
                       Set this keyword to the IDL window number where you
                       want the plot to appear (1 to 31).  The window size
                       is set to keep Mars round.

           DOALL:      Put the parameter, sampling, and rms/mean plots on a
                       single page.  Also includes a panel of text with
                       filter settings.  Set this keyword to the IDL window
                       number where you want the plot to appear (1 to 31).

           FILTER:     Set this flag to a structure defining a filter.  See
                       mvn_sta_cio_filter for more information.  If not set,
                       then no filter is applied, even if it is present in
                       the CIO data structure.

           LIMITS:     Structure of plotting options.  You can specify any
                       option(s) accepted by PLOT.  Reasonable defaults are
                       provided for all unspecified options.  To interpolate
                       the binned distribution function (not recommended), set
                       the tag 'no_interp' to zero.

           ZLIMITS:    Sampling plot Z limits, with 2 to 4 elements:

                               [zmin, zmax, zlog, zticks]

                       By default, the sampling plot has the same X and Y
                       limits and plotting options as the parameter plot
                       (as controlled by LIMITS).  Reasonable defaults are
                       provided for the Z axis, but you can override them
                       with this keyword.

           RLIMITS:    RMS/Mean plot Z limits, with 2 to 4 elements:

                               [rmin, rmax, rlog, rticks]

                       By default, the rms/mean plot has the same X and Y
                       limits and plotting options as the parameter plot
                       (as controlled by LIMITS).  Reasonable defaults are
                       provided for the Z axis, but you can override them
                       with this keyword.

           WSCALE:     Scale factor for sizing windows.  Default = 1 for a
                       an external monitor.  Use a smaller value for a laptop
                       monitor.

           EVEC:       Plot the convection electric field direction.
                       Default = 1 (yes) if BCLK is among the data filters.

           PNG:        Set this keyword to the full filename (including path)
                       for outputting a png plot.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-07 15:27:02 -0700 (Mon, 07 Apr 2025) $
     $LastChangedRevision: 33238 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_plot.pro $

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

(See projects/maven/swea/mvn_sta_cio_plot.pro)

## MVN_STA_CIO_RESTORE

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

    PROCEDURE:   mvn_sta_cio_restore
    PURPOSE:
      Restores STATIC cold ion outflow results.
      See mvn_sta_coldion.pro for details.

    USAGE:
      mvn_sta_cio_restore, trange

    INPUTS:
           trange:        Restore data over this time range.  If not specified, then
                          uses the current tplot range.

    KEYWORDS:
           LOADONLY:      Download but do not restore any cio data.

           RESULT_H:      CIO result structure for H+.

           RESULT_O1:     CIO result structure for O+.

           RESULT_O2:     CIO result structure for O2+.

           DOPLOT:        Make tplot variables.

           PANS:          Tplot panel names created when DOPLOT is set.

           SUCCESS:       Success flag.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-02-28 11:18:56 -0800 (Wed, 28 Feb 2018) $
     $LastChangedRevision: 24804 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_restore.pro $

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

(See projects/maven/swea/mvn_sta_cio_restore.pro)

## MVN_STA_CIO_SAVE

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

    PROCEDURE:   mvn_sta_cio_save
    PURPOSE:
      Saves STATIC cold ion outflow results in save/restore files.
      See mvn_sta_coldion.pro for details.

    USAGE:
      mvn_sta_cio_save, trange [, ndays]

    INPUTS:
           trange:        Start time or time range for making save files, in any
                          format accepted by time_double().  If only one time is
                          specified, it is taken as the start time and NDAYS is
                          used to get the end time.  If two or more times are
                          specified, then the earliest and latest times are used.
                          Fractional days (hh:mm:ss) are ignored.

           ndays:         Number of dates to process.  Only used if TRANGE has
                          only one element.  Default = 1.

    KEYWORDS:
           DODEN:         Calculate densities.  Default = 1 (yes).

           DOTEMP:        Calculate temperatures.  Default = 1 (yes).

           DOVEL:         Calculate temperatures.  Default = 1 (yes).

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-09-12 17:08:19 -0700 (Wed, 12 Sep 2018) $
     $LastChangedRevision: 25781 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_save.pro $

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

(See projects/maven/swea/mvn_sta_cio_save.pro)

## MVN_STA_CIO_SNAP

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

    PROCEDURE:   mvn_sta_cio_snap
    PURPOSE:
      Makes plots of statistics within individual pixels in maps created with
      mvn_sta_cio_plot.

    USAGE:
      mvn_sta_cio_snap, data

    INPUTS:
           data:       A data structure returned by mvn_sta_cio_plot.

    KEYWORDS:
           KEEP:       Keep the last snapshot window on exit.

           RESULT:     Structure to hold the last distribution on exit.

           RANGE:      Range for binning the data.  Default = minmax(data).

           NBINS:      Number of bins.  Default = 30.

           LPOS:       Legend position [X,Y], relative coordinates.

           ALLSTAT:    Include skewness and kurtosis in legend.

           CONSTANT:   Plot a vertical dashed line at this position.
                       Sets NOLINES = 1.

           CLABEL:     Labels across the top for each element of CONSTANT.

           NOLINES:    Do not plot lines for mean and median.

           This routine also passes keywords to PLOT.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-07 15:27:02 -0700 (Mon, 07 Apr 2025) $
     $LastChangedRevision: 33238 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_snap.pro $

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

(See projects/maven/swea/mvn_sta_cio_snap.pro)

## MVN_STA_CIO_STRUCT

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

    FUNCTION:   mvn_sta_cio_struct

    PURPOSE:
      Creates a Cold Ion Outflow data structure.

    INPUTS:
           NPTS:     Number of elements.  Default = 1.

    KEYWORDS:

    CREATED BY:      D. L. Mitchell.

    LAST MODIFICATION:
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-09-09 18:05:59 -0700 (Sun, 09 Sep 2018) $
     $LastChangedRevision: 25764 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_struct.pro $

(See projects/maven/swea/mvn_sta_cio_struct.pro)

## MVN_STA_CIO_TPLOT

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

    PROCEDURE:   mvn_sta_cio_tplot
    PURPOSE:

    USAGE:
      mvn_sta_cio_tplot

    INPUTS:

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-11-24 13:40:12 -0800 (Sat, 24 Nov 2018) $
     $LastChangedRevision: 26170 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_tplot.pro $

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

(See projects/maven/swea/mvn_sta_cio_tplot.pro)

## MVN_STA_CIO_UPDATE

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

    PROCEDURE:   mvn_sta_cio_update
    PURPOSE:
      Updates STATIC cold ion outflow results in save/restore files.

    USAGE:
      mvn_sta_cio_update, trange [, ndays]

    INPUTS:
           trange:        Start time or time range for making save files, in any
                          format accepted by time_double().  If only one time is
                          specified, it is taken as the start time and NDAYS is
                          used to get the end time.  If two or more times are
                          specified, then the earliest and latest times are used.
                          Fractional days (hh:mm:ss) are ignored.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-02-27 18:37:52 -0800 (Tue, 27 Feb 2018) $
     $LastChangedRevision: 24801 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_cio_update.pro $

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

(See projects/maven/swea/mvn_sta_cio_update.pro)

## MVN_STA_COLDION

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

    PROCEDURE:   mvn_sta_coldion
    PURPOSE:
      Loads STATIC data and calculates density, temperature, and velocity of
      H+, O+, and O2+.  The data are corrected for spacecraft potential and
      spacecraft motion when transforming to the MSO frame.  Thermal electron
      density from LPW is included as a check on the total ion density
      measured by STATIC.  Topology information based on the two-stream shape
      parameter (Xu) and PAD score (Weber) is attached to each measurement.
      A variety of ephemeris and geometry information are also included.

      This routine uses STATIC code developed by J. McFadden.

      This routine uses velocity moment code developed by Y. Harada and
      T. Hara.

    USAGE:
      mvn_sta_coldion

    INPUTS:
        None:          Data are loaded based on timespan.

    KEYWORDS:
        BEAM:          Use the beam version of the moment calculation.  Provides
                       the most accurate densities around periapsis.  Does not
                       work at all away from periapsis.

        POTENTIAL:     Use the composite spacecraft potential determined from
                       SWEA, STATIC, and LPW.  See mvn_scpot.pro for details.
                       This should always be set!  Default = 1.

        DENSITY:       Calculate densities for O+ and O2+.  If BEAM = 0, then
                       H+ density is also determined.  Automatically sets
                       POTENTIAL = 1.

        TEMPERATURE:   Calculate temperatures for O+ and O2+.  If BEAM = 0, then
                       H+ temperature is also determined.  Automatically sets
                       POTENTIAL = 1.

        VELOCITY:      Calculate velocities of H+, O+, and/or O2+.

                         VELOCITY = 1       --> calculate for all three species
                         VELOCITY = [0,0,1] --> calculate only for O2+

                       If you set this keyword, then you must load one of the
                       following APID's, in order of preference:

                          d1 -> 32E x  8M x 4D x 16A, burst time resolution
                          d0 -> 32E x  8M x 4D x 16A, survey time resolution
                          cf -> 16E x 16M x 4D x 16A, burst time resolution
                          ce -> 16E x 16M x 4D x 16A, survey time resolution

        BURST:         If set, try to use d1 if available, otherwise use d0.
                       If not set, use d0.

        FRAME:         Reference frame for velocities.  Default = 'mso'.  Try 'app'
                       to get apparent flow direction in APP frame.

        RESULT_H:      Result structure for H+.

        RESULT_O1:     Result structure for O+.

        RESULT_O2:     Result structure for O2+.

        PARNG:         Pitch angle range for 2-stream shape parameter.
                          1 : 0-30 deg  (default)
                          2 : 0-45 deg
                          3 : 0-60 deg

        TAVG:          Time averaging window size.  Improves statistics and
                       reduces run time.

        NOLOAD:        Skip the step of loading data.

        PANS:          Named variable to hold a space delimited string containing
                       the tplot variable(s) created.

        RESET:         Reinitialize the result structures.

        DOPLOT:        Make tplot variables of the results.

        SUCCESS:       Processing success flag.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-08-25 09:07:29 -0700 (Wed, 25 Aug 2021) $
     $LastChangedRevision: 30246 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_sta_coldion.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/swea/mvn_sta_coldion.pro)

## MVN_SWE_3DSUM

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

    FUNCTION:   mvn_swe_3dsum
    PURPOSE:
      Sums multiple 3D data structures.  This is done by summing raw counts
      corrected by deadtime and then setting dtc to unity.  Also, note that
      summed 3D's can be "blurred" by a changing magnetic field direction,
      so summing only makes sense for short intervals.  The theta, phi, and
      omega tags can be hopelessly confused if the MAG direction changes much.

    USAGE:
      dddsum = mvn_swe_3dsum(ddd)

    INPUTS:
           ddd:           An array of 3D structures to sum.

    KEYWORDS:

           QLEVEL:        Minimum quality level to sum (0-2, default=0):
                            2B = good
                            1B = uncertain
                            0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-07-06 13:42:55 -0700 (Thu, 06 Jul 2023) $
     $LastChangedRevision: 31939 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_3dsum.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_3dsum.pro

(See projects/maven/swea/mvn_swe_3dsum.pro)

## MVN_SWE_ADDEUV

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

    PROCEDURE:   mvn_swe_addeuv
    PURPOSE:
      Loads EUV data and creates tplot variable using EUV code.  EUV is
      measured in three bandpasses:

                       Photon      Photoelectron
        Wavelength		Energy		Energy (*)		Notes
       ----------------------------------------------------------------------
        121 nm			10.2 eV     N/A				Lyman-alpha
        17-22 nm		56-73 eV    42-59 eV (#)
        0.1-7 nm	    >177 eV     >163 eV			includes soft X-rays
       ----------------------------------------------------------------------
         * first ionization potential of CO2 is 13.77 eV
         # "Al edge" is near 60 eV

    USAGE:
      mvn_swe_addeuv

    INPUTS:
        None:          Data are loaded based on timespan.

    KEYWORDS:

        PANS:          Named variable to hold an array of the tplot
                       variable(s) created.

        NOFLAG:        If set, do not flag bad data.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-01-19 14:47:21 -0800 (Fri, 19 Jan 2018) $
     $LastChangedRevision: 24551 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addeuv.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/mvn_swe_addeuv.pro)

## MVN_SWE_ADDLPW

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

    PROCEDURE:   mvn_swe_addlpw
    PURPOSE:
      Loads LPW data and creates tplot variables using LPW code.

    USAGE:
      mvn_swe_addlpw

    INPUTS:
        None:          Data are loaded based on timespan.

    KEYWORDS:

        PANS:          Named variable to hold the tplot variable(s) created.

        MINCUR:        Minimum peak current in IV sweep for accepting LPW
                       density.  Default = 1e-7.  Quality filter for high-
                       altitude LPW densities suggested by Chris Fowler.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-01-19 14:47:21 -0800 (Fri, 19 Jan 2018) $
     $LastChangedRevision: 24551 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addlpw.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/mvn_swe_addlpw.pro)

## MVN_SWE_ADDMAG

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

    PROCEDURE:   mvn_swe_addmag
    PURPOSE:
      Loads MAG data from L2 or L1 save/restore files, rotates the MAG vectors to
      the SWEA frame, and stores the result in the SWEA common block for quick
      access by mvn_swe_getpad and mvn_swe_get3d.

      Note: If L2ONLY is set and L2 MAG PL data are unavailable, then this routine
      will attempt to load L2 MAG PC data and rotate to the PL frame using SPICE.
      This introduces a small error in the MAG vector direction that propagates
      from uncertainties in the spacecraft ck kernel.  The error is typically
      ~0.01 deg, except during spacecraft rotations when it can reach ~0.1 deg.
      These errors are negligible compared with the SWEA angular resolution of
      ~20 degrees, so pitch angle mapping remains accurate.

    USAGE:
      mvn_swe_addmag

    INPUTS:

    KEYWORDS:

        FULL:          The default priority order for loading is (highest to lowest):
                         L2_1SEC, L2_FULL, L1_1SEC, L1_FULL.

                       If set, then the priority order is: L2_FULL, L1_FULL.

        USEPADMAG:     If all else fails, then use the PAD angles as calculated
                       onboard.  In the best case, this close to MAG L1, except the
                       angular resolution is reduced (256 azimuths, 40 elevations).
                       In the worst case, it can be off by 10's of degrees.  Use with
                       caution!  Default = 0 (never use PAD angles).  If PAD angles
                       are used, the MAG level is set to zero.

        L2ONLY:        Insist on loading L2 data.  (Useful for generating PDS data.)

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-03 12:01:10 -0700 (Tue, 03 Jun 2025) $
     $LastChangedRevision: 33364 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addmag.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/mvn_swe_addmag.pro)

## MVN_SWE_ADDPOT

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

    PROCEDURE:       mvn_swe_addpot

    PURPOSE:         Overwrites SWEA spacecraft potentials with the
                     composite potential from mvn_scpot.

    INPUTS:
          none:      All information obtained from and written to common
                     blocks and tplot variables.

    KEYWORDS:
          LOADONLY:  Insert potential information into SPEC data but do not refresh
                     the tplot window.

    CREATED BY:      D. L. Mitchell

    LAST MODIFICATION:
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 10:26:29 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33408 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addpot.pro $

(See projects/maven/swea/mvn_swe_addpot.pro)

## MVN_SWE_ADDSEP

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

    PROCEDURE:   mvn_swe_addsep
    PURPOSE:
      Loads SEP data, sums over the look directions, and stores electron and ion
      energy spectra in tplot variables.

    USAGE:
      mvn_swe_addsep

    INPUTS:
        None:          Data are loaded based on timespan.

    KEYWORDS:

        PANS:          Named variable to hold an array of
                       the tplot variable(s) created.

        NOATT:         When averaging look directions, exclude data with the
                       attenuator is enabled.  Default = 1.

        FTO:           Make a panel for the omnidirectional FTO signal.

        TSMO:          Smoothing interval for FTO signal.  Default = 65 sec.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-11-13 11:21:33 -0800 (Wed, 13 Nov 2024) $
     $LastChangedRevision: 32960 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addsep.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/mvn_swe_addsep.pro)

## MVN_SWE_ADDSTA

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

    PROCEDURE:   mvn_swe_addsta
    PURPOSE:
      Loads STATIC data and creates tplot variables using STATIC code.
      By default APID's c0, c6, and ca are loaded.  This is sufficient
      to generate energy and mass spectra.  Optionally, you can also
      load additional APID's.

    USAGE:
      mvn_swe_addsta

    INPUTS:
        None:          Data are loaded based on timespan.

    KEYWORDS:
        APID:          Additional APID's to load.  This procedure always
                       loads c0, c6, and ca.  For example, set this keyword
                       to 'd0' (4D distributions) or 'd1' (4D distributions,
                       burst) in order to calculate velocity distributions.

        POTENTIAL:     Estimate the spacecraft potential from STATIC data.

        PANS:          Named variable to hold an array of the tplot
                       variable(s) created.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-01-03 10:05:18 -0800 (Mon, 03 Jan 2022) $
     $LastChangedRevision: 30486 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addsta.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/mvn_swe_addsta.pro)

## MVN_SWE_ADDSWI

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

    PROCEDURE:   mvn_swe_addswi
    PURPOSE:
      Loads SWIA data and calculates moments based on coarse survey.  All calculations
      are performed with the SWIA code, which stores the results as tplot variables.

    USAGE:
      mvn_swe_addswi

    INPUTS:
        None:          Data are loaded based on timespan.

    KEYWORDS:

        FINE:          Calculate moments with fine survey.  This provides better values
                       in the upstream solar wind.

        ALPHA:         Calculate both proton and alpha densities using SWIA code.
                       Requires 'fine' data, so this forces FINE to be set.

        PANS:          Named variable to hold an array of
                       the tplot variable(s) created.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-01-08 16:06:22 -0800 (Mon, 08 Jan 2024) $
     $LastChangedRevision: 32341 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_addswi.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/mvn_swe_addswi.pro)

## MVN_SWE_BACKGROUND

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

    PROCEDURE:   mvn_swe_background
    PURPOSE:
      At energies above ~1 keV, the SWEA count rate comes from three
      sources:  >1-keV electrons, penetrating high-energy particles, and
      radioactive decay of potassium 40 in the MCP glass.  Often, the
      background from penetrating particles and radioactive decay dominates
      the signal, so it is essential to remove this background to obtain
      reliable measurements of the >1-keV electron component.

      Protons with energies above ~20 MeV and electrons with energies above
      ~2 MeV can penetrate the instrument housing and internal walls to pass
      through the MCP, where they can trigger electron cascades and generate
      counts.  Lower energy electrons can partially penetrate and generate
      bremsstrahlung x-rays by interacting with the instrument's aluminum
      walls.  The x-rays can then penetrate to the MCP and trigger counts.
      Galactic Cosmic Rays (GCRs) peak near 1 GeV and easily pass through the
      instrument (and the entire spacecraft), resulting in a background count
      rate of several counts per second summed over all anodes.  GCR's are
      isotropic, but Mars effectively shields part of the sky.  Since MAVEN's
      orbit is elliptical, the GCR background varies along the orbit according
      to the changing angular size of the planet.  SEP events are episodic,
      but can increase the penetrating particle background by orders of
      magnitude for days.

      Since penetrating particles bypass SWEA's optics, they result in a
      constant count rate across SWEA's energy range.  The GCR background is
      ~1 count/sec/anode, varying by a factor of three over the solar cycle.
      Penetrating background can be identified by a constant count rate in
      SWEA's highest energy channels.  However, there are times when < 4.6 keV
      electrons are present at the same time as penetrating particles.  This
      is particularly true during SEP events.  When this happens, this routine
      will overestimate the background, so it may be necessary to fit the
      measured signal with a model that includes contributions from >1-keV
      electrons, penetrating particles, and radioactive decay.

      Potassium 40 has a half-life of ~1 billion years, so it generates a
      constant background.  This part of the background does not vary along
      the orbit, so it can in principle be separated from the GCR background.
      One good measurement of the potassium 40 background can be used for
      the entire mission.

      This routine estimates the penetrating particle background when the
      highest four energy channels (3.3 to 4.6 keV) exhibit a constant count
      rate.  If there is any slope in this energy range, then you should not
      use this routine, but instead do a 3-parameter fit to the measurements.

      This routine requires SPICE.

    USAGE:
      mvn_swe_background

    INPUTS:
      None.       SPEC data are obtained from the SWEA common block.

    KEYWORDS:
      K40:        If set, then fit for the radioactive decay background in
                  addition to the penetrating particle background.
                  Default = 0 (no).

      NBINS:      Number of altitude bins for the >3.3-keV count rate data.
                  Default = 30.

      MAXALT:     Set this keyword to the maximum altitude to include in the
                  fit.  Use this to base the fit solely on periapsis passes.
                  Reduce NBINS to maintain a reasonable number of points per
                  bin.  You may also need to load 3+ days of data to obtain
                  good statistics.  This keyword can be useful during SEP
                  events.

      INCLUDE:    If set, interactively include one or more time ranges for
                  the fit.  This can be used to select times when the >3.3-keV
                  count rate is constant.  Disabled when EXCLUDE is set.

      EXCLUDE:    If set, interactively exclude one or more time ranges from
                  the fit.  This can be used to exclude times when the >3.3-keV
                  count rate is not constant.  Takes precedence over INCLUDE.

      MASK:       Returns the mask used to select which data to use in the fit.
                  (0 = exclude, 1 = include).  You can also set this keyword to
                  a previous mask to make additional edits.

      ORBIT:      Mask data orbit by orbit.  Useful in combination with INCLUDE
                  and EXCLUDE during a SEP event, when the GCR background can
                  only be measured at periapsis on closed or deeply draped field
                  lines.  (Open field lines must be masked.)

      RESULT:     Returns the fitted/assumed results:
                    time    = center time of loaded data
                    trange  = time range of loaded data
                    alt     = altitude bins
                    data    = average >3.3-keV count rate in each bin
                    sdev    = statistical uncertainty
                    npts    = number of points in each bin
                    model   = count rate vs. altitude for best fit
                    units   = data, sdev, model units ('CRATE')
                    a       = penetrating background count rate corresponding
                              to zero shielding from Mars (alt -> infinity)
                    a_sigma = uncertainty in a
                    k40     = count rate from radioactive decay of potassium 40
                              in the MCP glass
                    k40_sigma = uncertainty in k40 (if applicable)

      RESIDUAL:   Show the residual (measured background - model) in the tplot
                  window.  Default = 0 (no).

      SHOWFIT:    If set, show the fit results in a separate window.  The top
                  panel shows the binned count rate vs. altitude along with the
                  best fit.  The next two panels show the number of samples per
                  bin and the Poisson correction.  Default = 0 (no).

      RESET:      Force a new altitude calculation.

    SEE ALSO:
       mvn_swe_secondary:  Calculates the secondary electron background.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-08-12 09:49:16 -0700 (Mon, 12 Aug 2024) $
     $LastChangedRevision: 32788 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_background.pro $

    CREATED BY:    David L. Mitchell  07-05-24
    FILE: mvn_swe_background.pro

(See projects/maven/swea/mvn_swe_background.pro)

## MVN_SWE_CALC_SHAPE_ARR

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

    PROCEDURE:
       mvn_swe_calc_shape_arr

    PURPOSE:
       Take an input spectrum and calculate the shape parameter

    AUTHOR:
       Shaosui Xu

    CALLING SEQUENCE:
       This procedure is called by mvn_swe_shape_pad

    INPUTS:

       NPTS: Number of electron energy spectrum

       FIN: Input electron energy spectrum

       Energy: The energy array corresponding to the electron energy spectrum

       ERANGE: The energy range given to calculate the shape parameter

       HRESFLG: If set to 1, then using high energy resolution (burst) pad data
                to calculate shape parameter. Usually, hresflg=0, survey pad data is used

    KEYWORDS:
       none

    OUTPUTS:
       PAR: Calculated shape parameter

     $LastChangedBy: xussui_lap $
     $LastChangedDate: 2016-06-22 17:22:28 -0700 (Wed, 22 Jun 2016) $
     $LastChangedRevision: 21352 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_calc_shape_arr.pro $

    CREATED BY:    Shaosui Xu  06-22-16

(See projects/maven/swea/mvn_swe_calc_shape_arr.pro)

## MVN_SWE_CALIB

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

    PROCEDURE:   mvn_swe_calib
    PURPOSE:
      Maintains SWEA calibration factors in a common block (mvn_swe_com).

    USAGE:
      mvn_swe_calib

    INPUTS:

    KEYWORDS:
           TABNUM:       Table number (1-8) corresponding to predefined settings:

                           1 : Xmax = 6., Vrange = [0.75, 750.], V0scale = 1., /old_def
                               primary table for ATLO and Inner Cruise (first turnon)
                                 -64 < Elev < +66 ; 7 < E < 4650
                                  Chksum = 'CC'X
                                  LUT = 0

                           2 : Xmax = 6., Vrange = [0.75, 375.], V0scale = 1., /old_def
                               alternate table for ATLO and Inner Cruise (never used)
                                 -64 < Elev < +66 ; 7 < E < 2340
                                  Chksum = '1E'X
                                  LUT = 1

                           3 : Xmax = 5.5, Vrange = [3./Ka, 750.], V0scale = 0., /old_def
                               primary table for Outer Cruise
                                 -59 < Elev < +61 ; 3 < E < 4630
                                  Chksum = 'C0'X
                                  LUT = 0
                                  GSEOS svn rev 8360

                           4 : Xmax = 5.5, Vrange = [2./Ka, 750.], V0scale = 1., /old_def
                               alternate table for Outer Cruise
                                 -59 < Elev < +61 ; 3 < E < 4650
                                  Chksum = 'DE'X
                                  LUT = 1
                                  GSEOS svn rev 8361

                           5 : Xmax = 5.5, Vrange = [3./Ka, 750.], V0scale = 0.
                               primary table for Transition and Science
                                 -59 < Elev < +61 ; 3 < E < 4630
                                  Chksum = 'CC'X
                                  LUT = 0
                                  GSEOS svn rev 8481

                           6 : Xmax = 5.5, Vrange = [2./Ka, 750.], V0scale = 1.
                               alternate table for Transition and Science
                                 -59 < Elev < +61 ; 3 < E < 4650
                                  Chksum = '82'X
                                  LUT = 1
                                  GSEOS svn rev 8482

                           7 : Xmax = 5.5, Erange = [200.,200.], V0scale = 0.
                               Hires 32-Hz at 200 eV
                                 -59 < Elev < +61 ; E = 200
                                  Chksum = '00'X
                                  LUT = 2

                           8 : Xmax = 5.5, Erange = [50.,50.], V0scale = 0.
                               Hires 32-Hz at 50 eV
                                 -59 < Elev < +61 ; E = 50
                                  Chksum = '00'X
                                  LUT = 3

                         Passed to mvn_swe_sweep.pro.

           CHKSUM:       Specify the sweep table by its checksum.  See above.
                         This only works for table numbers > 3.  Warning: Checksums
                         for tables 7 and 8 are the same, so using checksums to
                         specify sweep tables is now ambiguous.  See mvn_swe_getlut,
                         which resolves this ambiguity with housekeeping sweep
                         voltage readbacks and provides a more robust method of
                         determining which LUT is in use at any time.

           SETCAL:       Structure holding calibration factors to modify.  Structure can
                         have any combination of tags, which are recognized with case-
                         folded minimum matching (leading "swe_" is optional):

                           {swe_Ka       : 6.17      , $   ; analyzer constant
                            swe_G        : 0.009/16. , $   ; nominal geometric factor
                            swe_Ke       : 2.8       , $   ; electron suppression constant
                            swe_dead     : 1.0e-6    , $   ; deadtime per preamp
                            swe_min_dtc  : 0.25      , $   ; max 4x deadtime correction
                            swe_paralyze : 0            }  ; use non-paralyzable deadtime

                         Any other tags are ignored.

           DEFAULT:      Reset calibration factors to the default values (see above).

           LIST:         List the current calibration constants.

           SILENT:       Shhh.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-23 15:45:10 -0700 (Fri, 23 May 2025) $
     $LastChangedRevision: 33325 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_calib.pro $

    CREATED BY:    David L. Mitchell  03-29-13
    FILE: mvn_swe_calib.pro

(See projects/maven/swea/mvn_swe_calib.pro)

## MVN_SWE_CATALOG

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

    PROCEDURE:   mvn_swe_catalog
    PURPOSE:
      Looks in the SWEA L2 data directories and builds a catalog of files
      organized by type, year and month.

    USAGE:
      mvn_swe_catalog

    INPUTS:
           None.

    KEYWORDS:
           VERSION:       Look for L2 files with this version number.
                          Default is to use the current release version.

           REVISION:      Look for L2 files with this revision number.
                          Default is to look for the latest revision.

           MTIME:         Look for L2 files modified after this time.
                          Default is to look for all files regardless of
                          modification time.

           RESULT:        Named variable to hold the result structure
                          containing all valid file names organized by
                          type, year and month.

           VERBOSE:       Print out number of files of each type by
                          year and month.  This is the main point, so
                          the default is 1 (yes).

           TOUCH:         Change the access and modification times of
                          all files collected in RESULT to the current
                          time.  This can be used to "encourage" file
                          transfers to the SDC.  Works only in unix-like
                          environments.  Use with caution!

           TRANGE:        Search for files only within this time range.
                          Only year, month, day are used.

           DATES:         Search only for specific dates.  Can be an array
                          in any format accepted by time_double.

           PDS:           Search for files only in this PDS release
                          number or range.

           DROPBOX:       Place copies of the files into the dropbox.
                          This will force immediate delivery to the SDC.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-12 16:29:11 -0700 (Sun, 12 May 2024) $
     $LastChangedRevision: 32577 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_catalog.pro $

    CREATED BY:    David L. Mitchell  04-25-13
    FILE: mvn_swe_catalog.pro

(See projects/maven/swea/mvn_swe_catalog.pro)

## MVN_SWE_CLEAR

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

    PROCEDURE:   mvn_swe_clear
    PURPOSE:
      Clears the swe_dat common block.

         swe_hsk:  slow housekeeping
         a0:       3D survey
         a1:       3D archive
         a2:       PAD survey
         a3:       PAD archive
         a4:       ENGY survey
         a5:       ENGY archive
         a6:       fast housekeeping

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2019-03-15 16:00:57 -0700 (Fri, 15 Mar 2019) $
     $LastChangedRevision: 26826 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_clear.pro $

    CREATED BY:	David L. Mitchell  2013-07-26
    FILE:  mvn_swe_clear.pro

(See projects/maven/swea/mvn_swe_clear.pro)

## MVN_SWE_COM

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

    COMMON BLOCK:   mvn_swe_com
    PURPOSE:
      Stores the SWEA static memory.

         swe_hsk:  slow housekeeping
         a0:       3D survey
         a1:       3D archive
         a2:       PAD survey
         a3:       PAD archive
         a4:       ENGY survey
         a5:       ENGY archive
         a6:       fast housekeeping

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-15 11:25:13 -0700 (Thu, 15 May 2025) $
     $LastChangedRevision: 33310 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_com.pro $

    CREATED BY:	David L. Mitchell  2013-03-18
    FILE:  mvn_swe_com.pro

(See projects/maven/swea/mvn_swe_com.pro)

## MVN_SWE_CONFIG

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

    PROCEDURE:   mvn_swe_config
    PURPOSE:
      Maintains SWEA configuration changes in a common block (mvn_swe_com).
      Sweep table updates are handled by checksums (see mvn_swe_sweep) - times
      are recorded here as documentation.

      Mission phases are as follows:

        Event       Time (UTC)             Mission Phase
        -----------------------------------------------------------------------
        Launch      2013-11-18/18:28  -
                                       |-> Cruise
        MOI         2014-09-22/02:24  -
                                       |-> Transition (Commissioning)
        Sci Ops     2014-11-15/00:00  -
                                       |-> Primary Mission    (PDS R1 - R4)
        Ext Ops 1   2015-11-15/00:00  -
                                       |-> Extended Mission 1 (PDS R5 - R7.5)
        Ext Ops 2   2016-10-01/00:00  -
                                       |-> Extended Mission 2 (PDS R7.5 - R16)
        Ext Ops 3   2018-10-01/00:00  -
                                       |-> Extended Mission 3 (PDS R17 - R20)
        Ext Ops 4   2019-10-01/00:00  -
                                       |-> Extended Mission 4 (PDS R21 - R32)
        Ext Ops 5   2022-10-01/00:00  -
                                       |-> Extended Mission 5 (PDS R33 - R44)
        Ext Ops 6   2025-10-01/00:00  -
                                       |-> Extended Mission 6 (PDS R45 - R56)
        Ext Ops 7   2028-10-01/00:00  -
                                       |-> Extended Mission 7 (PDS R57 - R68)
        Ext Ops 8   2031-10-01/00:00  -
        -----------------------------------------------------------------------

    USAGE:
      mvn_swe_config

    INPUTS:

    KEYWORDS:

        LIST:          List configuration changes.  Set this keyword to one of
                       the following to list changes of a particular type:

                         'swp' : sweep table
                         'mtx' : MAG-to-SWE rotation matrix
                         'dsf' : deflection scale factors
                         'mcp' : MCP bias voltage (or SWE-SWI cross calibration)
                         'sup' : electron suppression

                       Otherwise, all changes are listed.

        TIMEBAR:       Returns a structure with three tags:

                         time : array of times for configuration changes
                         text : brief descriptions of configuration changes
                         type : types of configuration changes (see above)

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-23 15:45:39 -0700 (Fri, 23 May 2025) $
     $LastChangedRevision: 33326 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_config.pro $

    CREATED BY:    David L. Mitchell  03-29-13
    FILE: mvn_swe_config.pro

(See projects/maven/swea/mvn_swe_config.pro)

## MVN_SWE_CONVERT_QUALITY

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

    PROCEDURE:   mvn_swe_convert_quality
    PURPOSE:
      Converts olde format quality database into new format.

    USAGE:
      mvn_swe_convert_quality, trange

    INPUTS:
           trange:       One or more dates, in any format accepted by time_double.
                         Only full UT days are processed; any fractional part of
                         the day is ignored.  When trange has more than one element,
                         all days between the earliest and the latest (inclusive)
                         are processed.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-08-15 12:19:33 -0700 (Tue, 15 Aug 2023) $
     $LastChangedRevision: 32004 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_convert_quality.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/swea/mvn_swe_convert_quality.pro)

## MVN_SWE_CONVERT_UNITS

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

    PROCEDURE:
    	mvn_swe_convert_units
    PURPOSE:
    	Convert units for SPEC, PAD, and 3D data.
    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	mvn_swe_convert_units, data, units, SCALE=SCALE
    INPUTS:
    	Data: A 3D, PAD, or SPEC data structure for SWEA
    	Units: Units to convert the structure to.  Recognized units are:
                COUNTS : raw counts, uncorrected for deadtime
                RATE   : raw count rate, uncorrected for deadtime
                CRATE  : count rate, corrected for deadtime
                FLUX   : differential number flux (1/cm^2-s-ster-eV)
                EFLUX  : differential energy flux (eV/cm^2-s-ster-eV)
                E2FLUX : energy flux per energy bin (eV/cm^2-s-ster-bin)
                DF     : distribution function (1/(cm^3-(km/s)^3))
    KEYWORDS:
    	SCALE: Returns the array of conversion factors used
    OUTPUTS:
    	Returns the same data structure in the new units

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2019-03-15 12:42:31 -0700 (Fri, 15 Mar 2019) $
     $LastChangedRevision: 26814 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_convert_units.pro $

(See projects/maven/swea/mvn_swe_convert_units.pro)

## MVN_SWE_CRIB

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

    ======================================================================
     MAVEN SWEA Crib

     Additional information for all procedures and functions can be
     displayed using doc_library.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-11-13 11:19:21 -0800 (Wed, 13 Nov 2024) $
     $LastChangedRevision: 32958 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_crib.pro $
    ======================================================================

     BASIC OUTLINE FOR WORKING WITH PFP DATA.

     There is a basic approach you should follow when working with any
     of the PFP data products.

       Step 1: Set the time span.  Different syntaxes (syntaxi? syntaxae?)
               are possible.  Two common ones are:

    imespan, 'yyyy-mm-dd/hh:mm:ss', number_of_days
    imespan, ['yyyy-mm-dd/hh:mm:ss', 'yyyy-mm-dd/hh:mm:ss']

               Typically, one omits the '/hh:mm:ss' part.

       Step 2: Initialize SPICE.  This uses the time span from Step 1.
               There is more than one way to do this.  The standard
               method is to use mvn_spice_kernels and/or spice_kernel_load.
               I wrote a wrapper for those routines that also checks for
               and reports any coverage gaps.

    vn_swe_spice_init

       Step 3: Create tplot variables to visualize the spacecraft location
               and orientation.  Several panels are created, showing altitude,
               longitude, latitude, solar zenith angle, local time, etc.
               A color bar that indicates the spacecraft attitude along the orbit
               is useful to identify periods of Sun-point, Earth-point, and the
               various periapsis orientations.  Gaps in color show where the
               spacecraft is reorienting, so be careful about changing fields
               of view.

    aven_orbit_tplot, /loadonly
    vn_attitude_bar

               After this, you can plot snapshots of the orbit in three orthogonal
               MSO planes.  Optionally plot the orbit in cylindrical coordinates
               (/CYL),  IAU_MARS coordinates (MARS=1 or MARS=2), etc.  Use
               doc_library to see all the options.  (Each keyword opens a separate
               window.)  Press and hold the left mouse button and drag for a movie
               effect.

    aven_orbit_snap

     Tired of remembering and setting the keywords for maven_orbit_snap?  You
     can set defaults that remain active for your entire session:

    aven_orbit_options, {datum:'ell', mars=2, verbose:0, black:1}, /replace, /silent

     You can put this line in your idl_startup.pro.

     If you are planning on studying a few days scattered over a one month
     period, for example, it is more efficient to perform steps 1-3 for the
     entire month, and then load data within that month as needed.

       Step 4: Load data.  You can use the timespan from Step 1, or you can
               define a shorter timespan contained within it.  You can
               and should load data from multiple instruments without
               repeating the first three steps.  For example:

    imespan, smaller_time_range  ; optional
    vn_swe_load_l2, apid=['a2','a3','a4']
    vn_sta_l2_load, sta_apid=['c0','c6','ca','d0']

               Note that you don't have to know anything about file names,
               how to download the data, or where to put the data once you
               have it.  You also don't need to explicitly check version
               and revision numbers.  The software automatically checks for
               for this and downloads the latest version/revision if needed.
               All of this is done automatically based on the time span and
               data type.  Same goes for SPICE.

       Step 5: Create tplot variables and make a summary plot of the
               observations.  For convenience, you can load and display
               SWIA, STATIC and/or LPW data alongside the SWEA data using
               the /SWIA, /STATIC, and /LPW options.  But it's best for you
               to load those data yourself according to the SWIA and STATIC
               crib sheets.

    vn_swe_sciplot

       Step 6: Get the spacecraft potential.  Potentials are mostly in
               the range -20 to +10 Volts, but there are exceptions, such
               as the very low density solar wind (potential > +10) and
               the EUV shadow with high fluxes of energetic electrons
               (potential < -20).  If you are working with energies
               anywhere near the spacecraft potential, this step is
               critical -- ignoring it can give incorrect results!

    vn_scpot

       Step 7+: Work with the data as you wish.  When you want to go to
                a different time span, you must repeat steps 4-6, and
                possibly steps 1-3.

     ESA-SPECIFIC INFORMATION:

     Every time you work with ESA data (SWEA, SWIA, STATIC), you should ask
     yourself:

        AM I MISSING AN IMPORTANT PART OF THE DISTRIBUTION FUNCTION?

     The ESA's have blind spots in both angle and energy, so they can't
     measure the entire electron or ion distribution function.  The ESA's
     are mounted onto the spacecraft so that their fields of view span the
     important part of the distribution function much of the time.  For
     example, when the spacecraft is pointed at the Sun, SWIA is oriented so
     that the Sun direction is centered within its field of view.  In this
     orientation, SWIA can measure the upstream solar wind beam within its
     high-resolution "sweet spot".  SWIA can also measure the heated and
     deflected solar wind in the post-shock region most of the time.
     Similarly, during a periapsis pass, STATIC is oriented to capture the
     RAM ion beam in the center of its field of view, while the deflectors
     are used to measure the beam width in one dimension.  Watch out for
     times when the spacecraft is pointed at the Earth (usually for
     communications) or when the spacecraft is reorienting between orbit
     segments.  During these times, the fields of view are not optimized
     for science.

     Finite energy ranges also play a role.  SWIA does not measure below 25 eV,
     so it cannot measure cold, low-energy ions, which can dominate the
     distribution function close to the planet and in the wake.  STATIC is
     designed to measure down to tenths of an eV, but spacecraft charging can
     affect whether or not STATIC can measure low-energy ions.  The spacecraft
     charges negative in the ionosphere and in the optical shadow behind the
     planet, so STATIC can measure down to zero energy.  But in the sunlit
     region immediately outside the optical shadow, the spacecraft charges
     positive, which prevents STATIC from detecting any low-energy population.
     STATIC has four energy sweep tables (pickup, conic, ram, CO2) that are
     optimized for different altitude ranges.  At sweep table transitions,
     the high energy part of the distribution is often clipped when the energy
     range shrinks to measure colder plasma.  Beware of times in the ionosphere
     when the spacecraft charges more negative than about -5 Volts.  Large
     negative spacecraft potentials render STATIC's electrostatic attenuator
     ineffective, resulting in saturation.  (Large negative potentials at high
     altitudes, where the density is low, are not a problem.)

     SWEA measures from 3 eV to 4.6 keV.  Outside the ionosphere and in
     sunlight, the spacecraft charges positive, allowing SWEA to measure down
     to zero energy.  However, in the ionosphere, the main population of thermal
     electrons is well below SWEA's minimum energy, so that SWEA measures only
     primary photoelectrons (a few percent of the total density).  Thermal
     ionospheric electrons are measured by LPW.

     SWEA-SPECIFIC INFORMATION:

     General note: All SWEA procedures have their own documentation,
     describing how to call them and what the options are.  There are
     many more options than are listed in this help file.  To list the
     documentation for routine_name.pro:

    oc_library, 'routine_name'

     SWEA Data Products and APID's (hexadecimal):

        APID    Product Name      Product Description
      ---------------------------------------------------------------------------
         28     housekeeping      internal voltages and temperatures (L0 only)
         a0       svy3d           3D distributions (64E x 16A x 6D), survey
         a1       arc3d           3D distributions (64E x 16A x 6D), archive
         a2       svypad          PAD distributions (64E x 16P), survey
         a3       arcpad          PAD distributions (64E x 16P), archive
         a4       svyspec         SPEC distributions (64E), survey
         a5       arcspec         never used
         a6       fast hsk        high-rate voltages and temperatures (L0 only)
      ---------------------------------------------------------------------------

     Load SWEA L0 data into a common block.
       The advantages of loading from L0 are a smaller RAM footprint and
       access to instrument housekeeping.

    vn_swe_load_l0

     Load SWEA L2 data into a common block
       Data loaded from L2 are identical to data loaded from L0 (by design).
       L2 data load quickly but consume about 6 times more RAM.  A full day
       of L2 survey data can consume ~4 GB of RAM.  Add burst data to this
       and ~8 GB are needed.  So, you may need to manage RAM, depending on
       your hardware.

       All SWEA routines automatically detect which type of data are loaded
       and work the same.  L2 data are loaded using the same methods as L0:

    vn_swe_load_l2

     This will load all available APID's, both survey and burst.  If you
     have lots of RAM, you should do this.  To conserve RAM, you can load
     individual data products over different time ranges.  Make sure to use
     the NOERASE option, so that you don't reinitialize the common block
     with each call.

    vn_swe_load_l2, apid=['a4']        ; load SPEC survey data over the full range

    maller_trange = ['2014-12-10/10','2014-12-10/15'] ; spans at least one orbit
    vn_swe_load_l2, smaller_trange, apid=['a2','a3'], /noerase ; PAD survey and burst

     SWEA QUALITY FLAGS

     Starting in December 2018, a small fraction (< 0.01 %) of spectra exhibited
     reduced signal at energies below ~25 eV.  This occurred sporadically for
     individual spectra surrounded by normal spectra before and after, indicating
     that the instrument recovers quickly.  The anomaly rate increased to 0.04 % in
     January 2019, and then to ~1 % in February/March 2019.  By analyzing instrument
     housekeeping, we found that the occurrence rate of the anomaly is highly
     correlated with the analyzer temperature, as measured by a thermistor mounted
     on the anode board.  Higher temperatures increase the likelihood of the anomaly
     occurring.  In an attempt to suppress the anomaly, SWEA’s operating temperature
     was reduced on May 1, 2019.  This effectively reduced the anomaly rate to < 0.01 %
     for six months.  Even at the lower operating temperature, the anomaly reappeared
     in late November 2019, and has been present ever since.  In early 2020, the
     anomaly rate was ~15% and increased to ~30% by mid-2022.  It has remained stable
     at ~30% since then.

     With an anomaly rate of 30%, there are ~10^4 anomalous spectra per day, far too
     many to flag manually.  Software was designed to automatically identify anomalous
     spectra by cluster analysis of the signal in two energy ranges (3-6 and 6-12 eV).
     The algorithm is highly accurate when the flux is steady, as in the solar wind
     and the ionosphere.  Identification of the anomaly in the magnetosheath and tail
     is more difficult because the flux can be highly variable.  In addition, post-shock
     electron distributions in the sheath generate significant fluxes of secondary
     electrons at energies below 30 eV.  These secondary electrons are produced inside
     the instrument and thus are not suppressed by the anomaly.  Consequently, no attempt
     was made to identify anomalous spectra with high accuracy in the sheath and tail.
     Instead, a quality flag was defined to take on three values: 0 = the spectrum is
     affected by the anomaly; 1 = unknown; 2 = the spectrum is not affected by the
     anomaly.  This quality flag should be used as a guide, not as a definitive
     indicator.  The accuracy is high enough in the solar wind and ionosphere that
     routines that use quality filtering can be used to perform automated calculations
     with good accuracy.

     For detailed work on individual events, you will have to exercise judgement.
     With experience, you may discover that you can identify anomalous spectra better
     than the automated algorithm can.  You can edit quality flags with:

    vn_swe_edit_quality

     This is an interactive program that allows you change the quality level for
     individual spectra by clicking on them in a tplot window.  After this, filtering
     will be more effective.  Use caution!  Sometimes even humans have trouble
     confidently identifying anomalous spectra.  (Your edits will NOT be saved into
     the quality database.)

     As of Version 5, the SWEA L2 data include quality flags.  Quality flags are also
     provided when loading data from L0.  The SWEA code has been updated to recognize
     and use the quality flags.  You can set the minimum quality level for processing
     (QLEVEL) when calculating moments and estimating the spacecraft potential.

     ACCESSING OBSERVING GEOMETRY

     Determine the direction of the Sun in SWEA coordinates
       Requires SPICE.  There are several instances when the S/C
       Z axis is not pointing at the Sun (some periapsis modes,
       comm passes, MAG rolls).  When the sensor head is illuminated,
       increased photoelectron background can occur.  This routine
       also calculates the direction of the Sun in spacecraft
       coordinates -- useful to identify pointing modes and times
       when the spacecraft is communicating with Earth.

    vn_sundir, frame='swea', /polar, pans=pans

     Determine the RAM direction in spacecraft coordinates
       Requires SPICE.  The RAM direction is calculated with respect to
       the rotating IAU_MARS frame (planetocentric, body-fixed).

       Use keyword FRAME to calculate the RAM direction in any MAVEN
       frame recognized by SPICE.  See mvn_frame_name() for a list.

    vn_ramdir, pans=pans

     ELECTRON DENSITY AND KINETIC TEMPERATURE

     Estimate electron density and temperature from fitting the core to
     a Maxwell-Boltzmann distribution and taking a moment over energies
     above the core to estimate the contribution from the halo.  Remove
     secondary electrons before fitting.  Filter out known anomalous
     spectra (QLEVEL=1).

    vn_swe_n1d, /mb, pans=pans, /secondary, qlevel=1

     Estimate electron density and temperature from 1D moments.

    vn_swe_n1d, /mom, pans=pans, /secondary, qlevel=1

     Some notes for interpreting electron density and temperature calculations:

       (1) The calculated density is only for the part of the distribution
           function measured by SWEA.  When the spacecraft potential is
           positive, as in the solar wind, SWEA can measure to zero energy
           and thus measures nearly all of the distribution function.
           Typically, the contribution from electrons with energy > 4.6 keV
           is negligible.  In the ionosphere, most of the distribution is
           below SWEA's minimum energy of 3 eV, so SWEA measures only a
           small fraction of the total density.  In the magnetotail, the
           spacecraft charges negative and repels the low-energy portion
           of the distribution.  Again, SWEA measures only a fraction of
           the total density.  Always ask yourself: "Am I missing an
           important part of the distribution?"

       (2) Correction for the spacecraft potential is critical for
           calculating electron density.  The largest source of uncertainty
           typically propagates from the spacecraft potential estimate.

       (3) In the solar wind, secondary electron contamination is small but
           not negligible, typically affecting the density and temperature
           moments by ~10%.  In the sheath, secondary electron contamination
           is more pronounced, affecting the moments by ~25%.  You will not
           get good moments in the sheath unless you correct for spacecraft
           potential AND remove secondary contamination.

       (4) SWEA is cross-calibrated against SWIA, so the electron density is
           not independent of the ion density.  If the ion and electron density
           do not appear to agree, it is likely a field-of-view or energy range
           issue for one or both instruments.

       (5) Temperature fits and moments are best thought of as kinetic
           temperature.  In the solar wind, the core is often well fit with
           a bi-Maxwellian, with different temperatures parallel and perpen-
           dicular to the magnetic field.  The post-shock and ionospheric
           distributions are not Maxwellian.

     Resample the pitch angle distributions for a nicer plot.  SWEA measures
     the 0-180-degree pitch angle range twice.  This procedure averages these
     two independent measurements and oversamples.  Spacecraft blockage is
     masked automatically (by default).

    vn_swe_pad_resample, nbins=128., erange=[100., 150.], /norm, /mask, /silent

     Calculate pitch angle distributions from 3D distributions

    vn_swe_pad_resample, nbins=128., erange=[100., 150.], /norm, /mask, $
                        /ddd, /map3d, /silent

     Load resampled PAD data from pre-calculated IDL save/restore files into
     a TPLOT variable.  (Much faster than above, but may use L1 MAG data, and
     there are no options.)

    vn_swe_pad_restore

     SNAPSHOTS SELECTED BY THE MOUSE IN THE TPLOT WINDOW

       Tplot variables with two independent variables (time and some other
       parameter) are often displayed as color spectrograms, where the Y
       axis is the second independent variable and color represents the
       dependent variable (Z).  Sometimes, the color scale does not
       accurately portray the variation in Z, or it is difficult to tell
       whether a color gradient is significant.  For SWEA, energy spectra
       and pitch angle distributions are often shown in this way.

       If you want to have a better sense of the significance of color
       variations, then you can use SWEA snapshot programs that display
       data at a particular time (or time range) as line plots with error
       bars.  Time averaging helps to shrink the error bars, but this
       comes at the cost of reduced time resolution.  For PAD data, you
       should be careful to average over times when the magnetic field
       direction remains roughly constant, to avoid pitch angle smearing.

       IF YOU ARE GOING TO INTERPRET SOME COLOR GRADIENT IN A SPECTROGRAM,
       BE SURE TO LOOK AT SNAPSHOTS TO CONFIRM THE FEATURE IS SIGNIFICANT.
       THIS IS PARTICULARLY IMPORTANT FOR PAD SPECTROGRAMS.

       You can return data by keyword (ddd, pad, spec) at the last place
       clicked.  Use keyword SUM to sum data between two clicks.  (Careful
       with changing magnetic field.)  The structure element var (variance)
       keeps track of counting statistics, including digitization noise.
       Remove secondary electron contamination with keyword SECONDARY.
       Set the BURST keyword to show burst data instead of survey data.
       Filter out known anomalous spectra with keyword QLEVEL.

    we_engy_snap, /mom, /fixy, /secondary, spec=spec, qlevel=1
    we_pad_snap, energy=120, /secondary, pad=pad, qlevel=1
    we_3d_snap, /spec, /symdir, energy=120, ddd=ddd, smo=[5,1,1], qlevel=1

     For the PAD snapshots, setting keyword ENERGY produces a cut of the
     energy-pitch angle data at the specified energy.  You will see two
     groups of "plus" symbols, where the horizontal error bar shows the
     pitch angle range spanned by the bin, and the vertical error bar shows
     the statistical uncertainty.  There are two groups of symbols because
     SWEA measures the 0-180-deg pitch angle distribution twice, once for
     each half of the detector.  This way you can check for the statistical
     significance of pitch angle features, and you can verify gyrotropy.  For
     electrons, angular distributions in the plasma frame are nearly always
     gyrotropic, meaning that the flux is constant as a function of
     gyro-phase.  If you think you've discovered non-gyrotropic electrons or
     some never-before-seen pitch angle distribution, then you're probably
     looking at an instrumental effect.  Please contact us (see below).

     Tired of remembering and setting all of the keywords for the SWEA
     snapshot programs?  You can set defaults that remain active for
     your entire session:

    we_snap_options, {wscale:1.4, energy:120, resample:1, norm:1, maxrerr:0.9, spec:45, dir:1}, $
      /replace, /silent

     You can put this line into your idl_startup.pro to set up custom defaults
     for yourself.

     There is a generic tplot snapshot program with less functionality, but it
     works on any tplot variable with two independent variables (time and some
     other parameter) and one dependent variable.

    snap, var, [keyword=value, ...]

     I WANT NUMBERS NOT PLOTS!  HOW DO I GET NUMBERS?

     Get 3D, PAD, or SPEC data at a specified time or array of times.
       Use keyword ALL to get all 3D/PAD distributions bounded by
       the input time array.  Use keyword SUM to average all
       distributions bounded by the input time array.  Set the BURST
       keyword to get burst data instead of survey data.  (You have
       to load burst data first.  See above.)  Filter out known
       anomalous spectra using keyword QLEVEL.

    dd = mvn_swe_get3d(time, units='eflux', qlevel=1)
    ad = mvn_swe_getpad(time, qlevel=1)
    pec = mvn_swe_getspec(time, qlevel=1)

     Data can be converted to several different units:

       'counts' : raw counts
       'rate'   : raw count rate
       'crate'  : count rate, corrected for dead time
       'flux'   : 1/(cm2-sec-ster-eV)
       'eflux'  ; eV/(cm2-sec-ster-eV)
       'df'     ; distribution function: cm-3 (km/s)-3

     In most cases, the default is 'eflux'.  You can set units as
     in the example above, or you can change units at any time by:

    vn_swe_convert_units, data, units

     If you have loaded spacecraft potentials, then you can get
     and/or plot corrected data (in the plasma frame, far from the
     spacecraft) like this:

    dd = mvn_swe_get3d(time, units='eflux', /shiftpot, qlevel=1)
    ad = mvn_swe_getpad(time, /shiftpot, qlevel=1)
    pec = mvn_swe_getspec(time, /shiftpot, qlevel=1)

    we_engy_snap, /mom, /fixy, /secondary, spec=spec, /shiftpot, qlevel=1
    we_pad_snap, energy=130, /secondary, pad=pad, /shiftpot, qlevel=1
    we_3d_snap, /spec, /symdir, energy=130, ddd=ddd, smo=[5,1,1], /shiftpot, qlevel=1

     VISUALIZING THE ORBIT AND SPACECRAFT LOCATION OVER THE MISSION.

     Load the spacecraft ephemeris from MOI to the current date plus
     a few weeks into the future.  Uses reconstructed ephemeris data
     as much as possible, then predicts as far as NAIF provides them.
     Use the LOADONLY keyword to load the ephemeris into TPLOT without
     resetting the time range.  Warning: this routine will reinitialize
     SPICE, so you should do it in a separate instance of IDL.

     Ephemeris data are updated daily at 3:30 am Pacific.

    aven_orbit_tplot, /mission, /loadonly

     VISUALIZING THE ORBIT FAR INTO THE FUTURE.

     Ephemeris predicts are available that extend to the nominal end
     of mission at the end of 2031.  This is useful for long-range
     planning.  Warning: this routine will reinitialize SPICE, so you
     should do it in a separate instance of IDL.

    aven_orbit_predict

     After this, you can use maven_orbit_snap as usual.  The overall
     orbit evolution (its orientation in the MSO frame as a function of
     time) is reasonably well predicted.  However, the time of periapsis
     becomes highly uncertain just a few weeks into the future.  Note
     that the predicts make assumptions about atmospheric variability and
     orbit maintainence maneuvers that may or may not occur as planned.
     Inability to predict the atmospheric density is the main source
     of uncertainty.

     ESTIMATING THE PENETRATING PARTICLE BACKGROUND

     Protons with energies above ~20 MeV and electrons with energies above
     ~2 MeV can penetrate the instrument housing and internal walls to pass
     through the MCP, where they can trigger electron cascades and generate
     counts.  In addition, electrons below 2 MeV scatter off atoms in the
     instrument walls and emit bremsstrahlung radiation at x-ray energies
     (typically 10-30 keV).  These x-rays penetrate internal walls to impact
     the MCP and generate counts.  Finally, radioactive decay of potassium-40
     (half-life: 1.3 Gy) in the MCP glass emits electrons and positrons that
     can also contribute background counts.

     Galactic Cosmic Rays (GCRs, dominated by H+ and He++) are essentially
     isotropic and peak near 1 GeV.  They easily pass through the instrument
     and the entire spacecraft, resulting in a background count rate of
     several counts per second summed over all anodes.  The GCR background
     varies by a factor of two over the 11-year solar cycle, but should be
     essentially constant over time scales of days to weeks.

     SEP events are episodic, but can increase the penetrating particle
     background by orders of magnitude for days.  SEP events can contain
     both energetic ions and electrons.  In addition, SEP events often have
     an electron population below 5 keV that SWEA measures normally.  Thus,
     during SEP events, the 1-5-keV count rate can result from five sources:
     (1) < 5 keV electrons, (2) bremsstrahlung x-rays, (3) > 2 MeV electrons,
     (4) > 20 MeV protons, and (5) radioactive decay of potassium-40 in the
     MCP glass.

     If you are analyzing SWEA data at energies above ~1 keV, then you may
     want to consider subtracting this background.  During SEP events, this
     may be difficult because of the presence of 1-5-keV electrons; however,
     during quiet times, when the background is dominated by GCR's, the
     recommended approach is to use mvn_swe_background.  The header of that
     program contains instructions on how to use it.

     Because of the stochastic nature of the data, subtracting background
     can result in negative values.  You'll have to decide what to do in
     this case.

    vn_swe_background

     I HAVE QUESTIONS AND/OR I NEED HELP WITH ....

     If you have questions about the instrument or how to work with and
     interpret SWEA data, please contact us:

       Dave Mitchell - SWEA Lead        - davem@berkeley.edu
       Shaosui Xu    - SWEA Deputy Lead - shaosui.xu@berkeley.edu

     Before contacting us, please read over this crib sheet first.  Answers
     to some questions about SWEA IDL software can be found using doc_library,
     as described above.  If you're still stuck, send us an email.  If you're
     at SSL, feel free to stop by.

     If any of the SWEA IDL code crashes or otherwise causes problems, then
     send us an email.  It is very helpful to cut and paste details of the
     IDL session into your email -- the commands that lead up to the problem,
     along with any output and error messages that result.  It's ideal if you
     can recreate the problem from a fresh instance of IDL.  If we can
     reproduce the problem, we are much more likely to be able to fix it.
     If we can't reproduce the problem, that points to a configuration issue.
     Either way, we get to the bottom of your issue faster.

(See projects/maven/swea/mvn_swe_crib.pro)

## MVN_SWE_CROSSCAL

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

    FUNCTION:   mvn_swe_crosscal
    PURPOSE:
      Calculates SWEA-SWIA cross calibration factor as a function of time.
      Based on polynomial fits to numerous cross calibrations between SWEA
      and SWIA in the upstream solar wind, when both instruments were
      measuring the complete electron and ion distributions, respectively.
      Only periods of steady solar wind, when the spacecraft potential can
      be reliably estimated from SWEA data are used.

      The variation of the cross calibration factor with time after each
      MCPHV bump is well fit with a quadratic, so I'll allow extrapolation
      into periods with no solar wind coverage.

      Assumptions:

        (1) Charge neutrality.

        (2) SWIA is measuring the entire ion distribution.  This is safe
            in the upstream solar wind, as long as the spacecraft is Sun
            pointed, which is most of the time.  Watch out for times of
            Earth point.

        (3) The energy flux in SWEA's blind spots is the same as the
            average energy flux over the rest of the field of view.  This
            can be very much in error for the solar wind halo distribution;
            however, most of the density is in the core distribution, which
            is not strongly directional.

    USAGE:
      factor = mvn_swe_crosscal(time)

    INPUTS:
           time:         A single time or an array of times in any format
                         accepted by time_double().

    KEYWORDS:
           ON:           Turn cross calibation switch on.

           OFF:          Turn cross calibration switch off.

           REFRESH:      Refresh the polynomial coefficients.

           EXTRAP:       Extrapolate past the last measured cross calibration
                         factor using a polynomial fit to measurements since the
                         last MCPHV bump.  The default is to use the last
                         known value.

           SILENT:       Don't print any warnings or messages.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-01-22 14:39:31 -0800 (Wed, 22 Jan 2025) $
     $LastChangedRevision: 33078 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_crosscal.pro $

    CREATED BY:    David L. Mitchell  05-04-16
    FILE: mvn_swe_crosscal.pro

(See projects/maven/swea/mvn_swe_crosscal.pro)

## MVN_SWE_D2F_HEII

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

    PROCEDURE:
       mvn_swe_d2f_heii

    PURPOSE:
       To calculate second derivatives of energy flux, used in routine
       'mvn_swe_sc_negpot_twodir_burst'

    INPUTS:
       faway,ftwd,energy,ee

    KEYWORDS:

       ERANGE

    OUTPUTS:
       d2f_away,d2f_twd

     $LastChangedBy: xussui_lap $
     $LastChangedDate: 2017-12-01 11:52:37 -0800 (Fri, 01 Dec 2017) $
     $LastChangedRevision: 24384 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_d2f_heii.pro $

    CREATED BY:    Shaosui Xu  01-03-17

(See projects/maven/swea/mvn_swe_d2f_heii.pro)

## MVN_SWE_EDIT_QUALITY

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

    PROCEDURE:   mvn_swe_edit_quality
    PURPOSE:
      Interactively edit the quality flags by using the cursor and
      number keys.  Useful for editing a few quality flags.  Use at
      your own risk!

      To edit flags, SPEC data (APID A4) must be loaded, and you must
      have an energy spectrogram (swe_a4) visible in the tplot window.
      It can be part of a compound variable.

      Changes to quality flags are propagated to all SWEA data types
      (PAD and 3D, survey and archive) that are loaded.

       Quality flag definitions:

          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.

    USAGE:
      mvn_swe_edit_quality

    INPUTS:
           None

    KEYWORDS:
           None

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-02-27 11:56:33 -0800 (Tue, 27 Feb 2024) $
     $LastChangedRevision: 32460 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_edit_quality.pro $

    CREATED BY:  David Mitchell - January 2024

(See projects/maven/swea/mvn_swe_edit_quality.pro)

## MVN_SWE_EPARAM

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

    PROCEDURE:   mvn_swe_eparam
    PURPOSE:
      Calculates the gyrofrequency, gyroradius and adiabatic condition
      (1st adiabatic invariant) for electrons:

        Fg = (28 Hz)*B           ; gyrofrequency, [B] = nT

        Rg = (2.4 km)*sqrt(E)/B  ; gyroradius, [E] = eV, [B] = nT

        (1/B)*(dB/dx)*Rg << 1    ; adiabatic condition

        Ld = (7.43 m)*sqrt(T/n)  ; Debye length, [T] = eV, [n] = cm-3

      Collision frequencies (s-1) for electrons with neutrals ([Te] = K, [n] = cm-3)
      (from Ionospheres by Schunk & Nagy, Table 4.6 on pg. 99):
        N2    (2.33e-11) * n(N2)  * (1 - 1.21e-4*Te)*Te
        O2    (1.82e-10) * n(O2)  * (1 + 3.60e-2*sqrt(Te))*sqrt(Te)
        O     (8.90e-11) * n(O)   * (1 + 5.70e-4*Te)*sqrt(Te)
        He    (4.60e-10) * n(He)  * sqrt(Te)
        H     (4.50e-09) * n(H)   * (1 - 1.35e-4*Te)*sqrt(Te)
        CO    (2.34e-11) * n(CO)  * (Te + 165)
        CO2   (3.68e-08) * n(CO2) * (1 + 4.1e-11*abs(4500 - Te)^2.93)

    USAGE:
      mvn_swe_eparam

    INPUTS:
       None:      Mag data are obtained from tplot variable.  Spacecraft ephemeris
                  is obtained from common block.

    KEYWORDS:
       MINALT:    Below this altitude, electrons are assumed to be non-adiabatic
                  because of collisions with atmospheric species.

       ENERGY:    Electron energies (eV) for which to calculate parameters.
                  Default = [1000.,100.,10.]

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-08-25 09:33:52 -0700 (Wed, 25 Aug 2021) $
     $LastChangedRevision: 30250 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_eparam.pro $

    CREATED BY:    David L. Mitchell  09/18/15

(See projects/maven/swea/mvn_swe_eparam.pro)

## MVN_SWE_ESUPPRESS

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

    FUNCTION:   mvn_swe_esuppress
    PURPOSE:
      Calculates the SWEA electron suppression constant (Ke).  The correction is
      based on monthly calibration sequences, during which the sweep table
      alternates between table 5 (V0 disabled) and table 6 (V0 enabled) several
      times.

      Empirically, the energy dependence of the suppression behaves as if there
      is a slightly different work function near the entrance aperture (top cap
      and entrance to concentric hemispheres) compared with the hemispheres closer
      to the MCP.  This is modeled as two ESA's in series that have different
      analyzer constants.  The functional form of the correction factor is then an
      exponential:

          correction factor = exp(-(Ke/E_in)^2.)

      where E_in is the energy of the electron interior to the toroidal grids.
      When Ke = 0, the correction factor is unity.  Otherwise, there is a steep
      drop in sensitivity for E_in <~ Ke.

      This is the same functional form as observed for STATIC ion suppression.
      For STATIC, there is a clear time dependence over the mission and a
      directionality (mainly in RAM) that points to the influence of atomic O
      on internal STATIC surfaces, which are coated with CuO (commonly known by
      the trade name "Ebonol C").  The hypothesis is that atomic oxygen is
      altering the work function of CuO near the aperture.

      However, SWEA internal surfaces are coated with Cu2S instead of CuO, and
      there is no clear variation of the electron suppression with time.  This
      suggests that exposure to atomic O does not affect SWEA significantly, and
      consequently that the suppression has been present since launch.

    USAGE:
      Ke = mvn_swe_esuppress(time)

    INPUTS:
           time:         A single time or an array of times in any format
                         accepted by time_double().

    KEYWORDS:
           ON:           Enable suppression correction.

           OFF:          Disable suppression correction.

           SET:          Set the suppression constant to any fixed value > 0.
                         (This also enables the suppression correction.)  This
                         value remains persistent until you override it with a
                         different value or disable it altogether with SET = 0.
                         Note that SET = 0 reverts to the nominal suppression
                         constant; it does not disable the correction.

                         This is useful for fine tuning the correction,
                         especially outside of the calibrated time range
                         (2015-03-01 to 2016-09-01).

           SILENT:       Don't print any warnings or messages.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-10-02 16:44:57 -0700 (Mon, 02 Oct 2017) $
     $LastChangedRevision: 24086 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_esuppress.pro $

    CREATED BY:    David L. Mitchell  2016-09-13
    FILE: mvn_swe_esuppress.pro

(See projects/maven/swea/mvn_swe_esuppress.pro)

## MVN_SWE_ETSPEC

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

    PROCEDURE:
    	MVN_SWE_ETSPEC

    PURPOSE:
    	Makes tplot variables with respect to the MAVEN SWEA
           Energy-time spectrogram(s).

    CALLING SEQUENCE:
           mvn_swe_etspec, ['2014-11-17/08:04:19', '2014-11-17/12:40:31'], $
                          units='eflux', data_type='3d', $
                          angle='pa', /default

    INPUTS:
       none - 3D, PAD, or SPEC  data are obtained from SWEA common block.
       If you set the time interval, then a tplot variable is created
       between you specified time intervals.
       (Noted that it might take more than 10 minutes to resample pitch
       angle distributions if you use PAD data for 1 day, depending on
       your machine spec and data amount.)

    KEYWORDS:
       TRANGE:    Instead of an input variable, you can alternatively specify
                  the time interval when you want to create a tplot variable.

       DATA_TYPE: Chooses the data product type ('3d', 'pad', or 'spec')
                  Default is 'spec'.

       ERANGE:    Specifies energy range over which you want to plot .
                  Default is the whole enegy range.

       UNITS:     Sets the unit to prefer to use. Default = 'crate'.

       ANGLE:     Selects the angular spectrum. Now 'pa' is only available.
                  'pa' means it can plot the pitch-angle-sorted, energy-time
                  spectrogram. In near future, 'phi'(= azimuth anode),
                  'theta'(= deflection angle) will be available.

       PHI:       Limits the azimuth anode (or looking direction) as
                  2-elements array [min, max], in degrees.

       THETA:     Limits the deflection angle (or lookgin direction) as
                  2-elements array [min, max], in degrees.

       PITCH:     Limits the pitch angle as 2-elements array [min, max],
                  in dgrees. If it is used, 'mvn_swe_pad_resample' is
                  automatically executed.

       SUFFIX:    Sets a tplot suffix to apply when generating outputs.

       MASK:      Masks the expected angular bins whose field of view is
                  blocked by the spacecraft body and solar
                  paddles. Automatically identifying the mission phases
                  (cruise or science mapping).

       STOW:      (Obsolete). Mask the angular bins whose field of view
                  is blocked before the boom deploy.

       ARCHIVE:   Uses the archive data, instead of the survey data.

       WINDOW:    Set the window number to show the snapshot. Default = 0.

       ABINS:     Specify which anode bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1,16)

       DBINS:     Specify which deflection bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1,6)

       MBINS:     Specify which angular (both anode and deflection) bins
                  to include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1, 96)

       SC_POT:    Account for the spacecraft potential correction.
                  (Not completely activated yet)

       VERBOSE:   Controls how often the processing information is shown
                  onto the terminal.

       Default:   If you use this keyword, the following tplot variables
                  are automatically created:
                  If you also use the keyword as angle='pa',
                     - quasi-parallel (0-30 deg),
                     - quasi-perpendicular (75-105 deg),
                     - quasi-antiparallel (150-180 deg),
                  Above 3 directional pitch-angle-sorted energy-time spectrograms
                  are created.
                  If you do NOT use 'angle' keyword,
                     - sunward      (+ MSO_X)
                     - anti-sunward (- MSO_X)
                     - duskward     (+ MSO_Y)
                     - dawnward     (- MSO_Y)
                     - northward    (+ MSO_Z)
                     - southward    (- MSO_Z)
                  Above 6 directional enegry-time spectrograms
                  are created if SPICE/Kernels are available.

      FRAME:      Sets the coordinate system to define the direction.
                  In the present version, the coordinate system(s)
                  derived from the SPICE/Kernels are available,
                  e.g., 'MAVEN_MSO', 'IAU_MARS', 'MAVEN_SWEA' or so on.

    CREATED BY:      Takuya Hara on 2014-11-22.

     $LastChangedBy: hara $
     $LastChangedDate: 2015-08-12 20:41:21 -0700 (Wed, 12 Aug 2015) $
     $LastChangedRevision: 18478 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_etspec.pro $

    MODIFICATION LOG:
    (YYYY-MM-DD)
     2014-11-22: Starts to prepare this routine.

(See projects/maven/swea/mvn_swe_etspec.pro)

## MVN_SWE_FLATFIELD

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

    FUNCTION:   mvn_swe_flatfield
    PURPOSE:
      Maintains the angular sensitivity calibration and provides a means to
      enable and disable the correction.  See mvn_swe_fovcal for details.
      You can choose only one action: ON, OFF, or SET.  If you don't specify
      an action, no change is made, and the routine only reports its current
      state.

      Calibrations are performed in the solar wind, using the strahl as a
      calibration beam.  As the magnetic field direction changes, different
      parts of the FOV are "illuminated".  Electron 3D distributions are
      corrected for spacecraft potential and transformed to the plasma rest
      frame (using SWIA data), where the gyrotropy condition applies.
      Correction factors are then determined for each of the 96 angular bins
      that symmetrizes the angular distribution with respect to the magnetic
      field direction.  To date, the solar wind calibration periods are:

          1 : 2014-10-27 to 2015-03-14
          2 : 2015-06-10 to 2015-10-15
          3 : 2015-12-13 to 2016-04-05
          4 : 2016-05-29 to 2016-10-06
          5 : 2016-11-28 to 2017-03-15
          6 : 2017-06-13 to 2017-08-22
          7 : 2017-12-10 to 2018-04-25
          8 : 2018-06-23 to 2018-11-13 (break at MCP bump)
          9 : 2018-11-13 to 2019-03-25
         10 : 2019-05-08 to 2019-08-14
         11 : 2019-10-23 to 2019-12-23
         12 : 2020-03-03 to 2020-05-07
         13 : 2020-07-25 to 2020-10-14
         14 : 2021-01-10 to 2021-03-06
         15 : 2021-06-05 to 2021-07-18
         16 : 2021-10-06 to 2022-01-08
         17 : 2022-06-23 to 2022-09-30
         18 : 2022-11-25 to 2023-02-21
         19 : 2023-05-11 to 2023-06-29
         20 : 2023-09-16 to 2023-12-05
         21 : 2024-02-29 to 2024-05-17
         22 : 2024-08-08 to 2024-09-26
         23 : 2024-12-13 to 2025-02-26
         24 : 2025-05-02 to ???

      Solar wind periods 1 and 3 yield calibrations that are very similar.
      These are combined into a single FOV calibration.  Solar wind period
      2 occurred when the SWEA MCP bias was not optimized.  The lower MCP
      gain results in a measurably different FOV sensitivity.  Periods 9
      and later all have the same MCP bias (2875 V).

      Once set, a configuration is persistent within the current IDL session
      until changed with this routine.

    USAGE:
      ff = mvn_swe_flatfield(time)

    INPUTS:
           time:         Specify the time (in any format accepted by time_double)
                         for calculating the flatfield correction.

    KEYWORDS:
           NOMINAL:      Enable the nominal correction.

           SET:          Set the flatfield to this 96-element array.

           OFF:          Disable the correction.

           SILENT:       Don't print any warnings or messages.

           INIT:         Reinitialize the flatfield common block.

           TEST:         Returns calibration used.  For testing.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-15 11:28:54 -0700 (Thu, 15 May 2025) $
     $LastChangedRevision: 33314 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_flatfield.pro $

    CREATED BY:    David L. Mitchell  2016-09-28
    FILE: mvn_swe_flatfield.pro

(See projects/maven/swea/mvn_swe_flatfield.pro)

## MVN_SWE_FLATFIELD_TEST

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

    PROCEDURE:   mvn_swe_flatfield_test
    PURPOSE:

    USAGE:
      mvn_swe_flatfield_test

    INPUTS:

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-11-07 16:17:37 -0800 (Tue, 07 Nov 2023) $
     $LastChangedRevision: 32219 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_flatfield_test.pro $

    CREATED BY:    David L. Mitchell  2016-09-28
    FILE: mvn_swe_flatfield_test.pro

(See projects/maven/swea/mvn_swe_flatfield_test.pro)

## MVN_SWE_FOVCAL

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

    PROCEDURE:   mvn_swe_fovcal
    PURPOSE:
      Given 3D electron distributions, the magnetic field direction, the
      solar wind velocity, and the spacecraft potential, this routine
      estimates the relative sensitivities of the SWEA 3D angular bins.
      The technique takes advantage of the fact that the electron
      distribution should be very nearly gyrotropic in the plasma rest
      frame.

      Assumptions: (1) The measured magnetic field vector is accurate, and
                       apparent deviations from gyrotropy are caused entirely
                       by uncompensated variations in sensitivity around the
                       field of view.

                   (2) A polynomial fit to the measured distribution is a
                       reasonable approximation to the "true" distribution.
                       Corollary: There are no sharp features in the pitch
                       angle distribution.

      Errors caused by (1) can be minimized by comparing the magnetic field
      vector to the symmetry direction of the electron angular distribution.
      Only times when these two directions agree to within a fraction of a
      ~20-deg-wide angular bin are used.  Exceptions can be made when the
      magnetic field vector is in or near one of SWEA's blind spots, in which
      case the symmetry direction is ill defined.  See swe_3d_strahl_dir.

      Errors caused by (2) can be minimized by visually inspecting the fits
      before adding the calibration to the database.  There are, occasionally,
      sharp features in the pitch angle distribution, and these should be
      avoided.

      Since the calibration is based on numerous pitch angle distributions,
      each with its own polynomial fit, the assumption is that any remaining
      errors introduced by (1) and (2) will be averaged out.

    USAGE:
      mvn_swe_fovcal, result=result

    INPUTS:

    KEYWORDS:
           UNITS:     Units.

           MINCNTS:   Minimum number of raw counts for calculating the result.
                      Used to ensure reasonable statistics. Default = 30.

           ORDER:     A one- or two-element integer array specifying the
                      polynomial orders for each half of the pitch angle
                      distribution.  Default = [4,4].

           MIDPA:     Pitch angle at which to divide the spectrum for fitting
                      each polynomial.  Default = 90 deg.

           OLAP:      Pitch angle width for overlapping MIDPA for polynomial
                      fits.  Produces more reasonable fits by constraining the
                      polynomial to continue going through data points beyond
                      MIDPA.  Default = 10 deg.

           ENERGY:    Energy at which to perform the calibration.  Default is
                      125 eV.

           SYMDIR:    Use the 3D symmetry direction instead of the magnetic
                      field vector.  Use with caution, since this routine is
                      symmetrizes the distribution based on this direction.

           SCP:       Set the spacecraft potential to this value.

           CALNUM:    Set the nominal calibration to this solar wind period.
                      Default = 1.

           RESULT:    A structure containing the time and a 96-element array
                      containing the relative geometric factors for the 3D
                      bins.

           KILLWINS:  Delete the windows upon completion.  Default is to keep
                      and reuse them for subsequent plots.

    CREATED BY:	David L. Mitchell  2016-08-03

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-06-05 12:17:33 -0700 (Mon, 05 Jun 2023) $
     $LastChangedRevision: 31883 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_fovcal.pro $

(See projects/maven/swea/mvn_swe_fovcal.pro)

## MVN_SWE_FOVMAP

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

    PROCEDURE:   mvn_swe_fovmap
    PURPOSE:
      Calculates the SWEA FOV in the form of an array of unit vectors pointing to each
      solid angle resolution element.  This is stored in a common block for later use
      by mvn_swe_padmap.

    USAGE:
      mvn_swe_fovmap

    INPUTS:
           none

    KEYWORDS:
           RESET:         Initialize the common block, which contains the unit vectors
                          pointing to each element of the FOV.

           PATCH_SIZE:    Number of resolution elements, N, in azimuth and elevation for
                          each of the 96 solid angle bins.  This oversamples each solid
                          angle bin with an N x N grid.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-15 11:27:34 -0700 (Thu, 15 May 2025) $
     $LastChangedRevision: 33312 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_fovmap.pro $

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

(See projects/maven/swea/mvn_swe_fovmap.pro)

## MVN_SWE_FOVPLOT

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

    PROCEDURE:   mvn_swe_fovplot
    PURPOSE:
      Plots the results of a FOV calibration obtained with mvn_swe_fovcal.

    USAGE:
      mvn_swe_fovplot, dat, result=result

    INPUTS:
           dat1:      A FOV calibration structure obtained with mvn_swe_fovcal.

           dat2:      A FOV calibration structure obtained with mvn_swe_fovcal.
                      If present, create the ratio dat2/dat and propagate errors.

    KEYWORDS:
           BAD:       A set of solid angle bins to ignore when calculating the
                      azimuth and elevation responses.  Bins blocked by the
                      spacecraft are automatically ignored.

           DATE:      Date string associated with calibration ('MMM YYYY').

           CRANGE:    Color scale range.  Default = [0.5,1.5].

           YRANGE:    RGF range for data point plot.  Default = [0,1.4].

           MAP:       Mapping projection.  Can be one of:
                         'mol' = Mollweide
                         'cyl' = Cylindrical
                         'ort' = Orthographic
                         'ait' = Aitoff (default)
                         'lam' = Lambert
                         'gno' = Gnomic
                         'mer' = Mercator

           LON:       Center longitude for 3D map.  Default = 180.

           LAT:       Center latitude for 3D map.  Default = 0.

           RESULT:    Structure containing the azimuth and elevation responses
                      with uncertainties.

           CAT:       Print the results.

           PSNAME:    File name for postscript output.

    CREATED BY:	David L. Mitchell  2016-08-03

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-06-05 12:17:33 -0700 (Mon, 05 Jun 2023) $
     $LastChangedRevision: 31883 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_fovplot.pro $

(See projects/maven/swea/mvn_swe_fovplot.pro)

## MVN_SWE_GET3D

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

    FUNCTION:   mvn_swe_get3d
    PURPOSE:
      Returns a SWEA 3D data structure constructed from L0 data or extracted
      from L2 data.  This routine automatically determines which data are loaded.
      Optionally sums the data over a time range, propagating uncertainties.

    USAGE:
      ddd = mvn_swe_get3d(time)

    INPUTS:
           time:          An array of times for extracting one or more 3D data structure(s)
                          from survey data (APID A0).  Can be in any format accepted by
                          time_double.

    KEYWORDS:
           ARCHIVE:       Get 3D data from archive instead (APID A1).

           BURST:         Synonym for ARCHIVE.

           ALL:           Get all 3D spectra bounded by the earliest and latest times in
                          the input time array.  If no time array is specified, then get
                          all available spectra from the currently loaded data.

           SUM:           If set, then sum all 3D's selected.

           UNITS:         Convert data to these units.  (See mvn_swe_convert_units)

           SHIFTPOT:      Correct for spacecraft potential.

           QLEVEL:        Minimum quality level to load (0-2, default=0):
                            2B = good
                            1B = uncertain
                            0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-17 15:22:14 -0700 (Thu, 17 Apr 2025) $
     $LastChangedRevision: 33264 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_get3d.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_get3d.pro

(See projects/maven/swea/mvn_swe_get3d.pro)

## MVN_SWE_GETBITS

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

    FUNCTION:   mvn_swe_getbits
    PURPOSE:
      Extracts a sub-word defined by a range of bits from an input word.

    USAGE:
      subword = mvn_swe_getbits(word, bitrange)

    INPUTS:
           word:          A 16-bit (2-byte) word.  Can also be an array of words.
                          Can also be a byte or an array of bytes.

           bitrange:      A one- or two-element array specifying the desired bit or
                          range of bits: [MSB [, LSB]], where MSB and LSB are integers
                          between 0 and 15.  If MSB and LSB are the same, or if only
                          one bit is specified, then just that one bit is returned.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-10-31 12:38:38 -0700 (Fri, 31 Oct 2014) $
     $LastChangedRevision: 16103 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_getbits.pro $

    CREATED BY:    David L. Mitchell  08-29-11
    FILE: mvn_swe_getbits.pro
    VERSION:   1.0
    LAST MODIFICATION:   08/29/11

(See projects/maven/swea/mvn_swe_getbits.pro)

## MVN_SWE_GETLUT

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

    PROCEDURE:   mvn_swe_getlut
    PURPOSE:
      Determines the sweep lookup table used for each 2-sec measurement
      cycle.  This information is stored in the SPEC, PAD, and 3D data
      structures.  The vast majority of the time a single sweep table is
      used, in which case this routine is trivial.  The exceptions are
      power on, monthly calibrations (until late 2019) and high time
      resolution campaigns.  The latter two use rapid mode toggling, so
      that high cadence housekeeping is needed to keep track of the mode
      changes.  Even then, there are occasional mismatches between the
      sweep table reported in housekeeping and the one actually used for
      measurements.  Three methods are provided (via keyword) to identify
      and correct these mismatches.  None is perfect, but at least one of
      them, depending on the circumstances, has been able to identify all
      table changes correctly ... so far.

      Method 1: Use SSCTL values in housekeeping to identify the table.
        This requires high-cadence housekeeping.  The SSCTL values are
        not accurately synced with the data, and it is possible for the
        timing to be off by a second or more.  Thus, this method can
        assign incorrect sweep tables.  Keyword DT_LUT can be used to
        shift SSCTL times by a constant amount to align with the data.

      Method 2: Use analyzer voltage readback in housekeeping to identify
        tables 7-9.  This works well much of the time, but can get
        confused when the sweep in normal operation is sampled near one
        of the high-cadence energies.

      Method 3: Use a constant count rate at all energy steps to detect
        one of the high-cadence tables.  This assumes that the signal
        changes slowly during the 2-second measurement cycle.  This is
        used in conjunction with Method 1 to correct SSCTL timing errors.
        This is the least effective method, because during interesting
        times, the signal can change significantly within a measurement
        cycle.  It also fails within superthermal electron voids, where
        the flux at all energy channels is near background.

    USAGE:
      mvn_swe_getlut

    INPUTS:
           None.

    KEYWORDS:
           DT_LUT:   Time offset between housekeeping SSCTL values and
                     science data.  Units: sec.  Default = 0D.

           VOLT:     Use analyzer voltage readback in housekeeping to
                     identify tables 7-9.

           VMEAN:    Mean values of the ANALV readback for 50, 125, and
                     200 eV, as recorded in flight.

                        Ideal   = [ 7.97, 20.24, 32.26]
                        Actual  = [ 8.23, 20.52, 32.50]  <-- default
                        Stddev  = [ 0.30,  0.22,  0.25]
                        Spacing = [ 0.88,  2.22,  3.55]  ; step spacing (Volts)
                        Spacing = [ 2.93, 10.09, 14.20]  ; step spacing (sigma)

                     The ANALV readback is systematically high by about
                     0.25 Volts, or one standard deviation.

           DV_MAX:   Maximum absolute difference between measured analyzer
                     voltage and nominal voltage.  Three values: one each
                     for 50, 125, and 200 eV.  Default: [0.7, 1.5, 2.0].

           FLUX:     Use constant flux at all energy steps to determine if
                     one of the high-cadence tables (7-9) is in use.  If so,
                     then the nearest housekeeping SSCTL value uniquely
                     identifies which table is in use.

           RESULT:   Table number for each SPEC.

           TPLOT:    Make a tplot variable of LUT vs time.

           DIAG:     Make diagnostic plots to evaluate and tune VOLT method.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-23 15:46:17 -0700 (Fri, 23 May 2025) $
     $LastChangedRevision: 33327 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_getlut.pro $

(See projects/maven/swea/mvn_swe_getlut.pro)

## MVN_SWE_GETPAD

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

    FUNCTION:   mvn_swe_getpad
    PURPOSE:
      Returns a SWEA PAD data structure constructed from L0 data or extracted
      from L2 data.  This routine automatically determines which data are loaded.
      Optionally sums the data over a time range, propagating uncertainties.

    USAGE:
      pad = mvn_swe_getpad(time)

    INPUTS:
           time:          An array of times for extracting one or more PAD data structure(s)
                          from survey data (APID A2).  Can be in any format accepted by
                          time_double.

    KEYWORDS:
           ARCHIVE:       Get PAD data from archive instead (APID A3).

           BURST:         Synonym for ARCHIVE.

           ALL:           Get all PAD spectra bounded by the earliest and latest times in
                          the input time array.  If no time array is specified, then get
                          all PAD spectra from the currently loaded data.

           SUM:           If set, then sum all PAD's selected.

           UNITS:         Convert data to these units.  (See mvn_swe_convert_units)
                          Default = 'eflux'.

           SHIFTPOT:      Correct for spacecraft potential.

           L0:            Force loading from L0.

           QLEVEL:        Minimum quality level to load (0-2, default=0):
                            2B = good
                            1B = uncertain
                            0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 16:20:05 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33413 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_getpad.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_getpad.pro

(See projects/maven/swea/mvn_swe_getpad.pro)

## MVN_SWE_GETSPEC

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

    FUNCTION:   mvn_swe_getspec
    PURPOSE:
      Returns a SWEA SPEC data structure constructed from L0 data or extracted
      from L2 data.  This routine automatically determines which data are loaded.
      Optionally sums the data over a time range, propagating uncertainties.

    USAGE:
      spec = mvn_swe_getspec(time)

    INPUTS:
           time:          An array of times for extracting one or more SPEC data structure(s).
                          Can be in any format accepted by time_double.  If more than one time
                          is specified, then all spectra between the earliest and latest times
                          in the array are returned.

                          If no time is specified, then return all SPEC data that are currently
                          loaded.

    KEYWORDS:
           ARCHIVE:       Get SPEC data from archive (APID A5).

           BURST:         Synonym for ARCHIVE.

           SUM:           If set, then sum all spectra selected.

           UNITS:         Convert data to these units.  Default = 'EFLUX'.

           SHIFTPOT:      Correct for spacecraft potential.  It is recommended that you first
                          determine the spacecraft potential using mvn_scpot and then assess
                          the quality of the potential estimates before trying to use this
                          keyword.

           YRANGE:        Returns the data range, excluding zero counts.

           QLEVEL:        Minimum quality level to load (0-2, default=0):
                            2B = good
                            1B = uncertain
                            0B = affected by low-energy anomaly

           MAXDT:         Tolerance for the input time aligning with a data time tag.
                          If there is no data time tag within MAXDT of the input time,
                          then no data are returned.  Default = 4 sec.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-04 14:47:18 -0700 (Sat, 04 May 2024) $
     $LastChangedRevision: 32548 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_getspec.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_getspec.pro

(See projects/maven/swea/mvn_swe_getspec.pro)

## MVN_SWE_HSKPLOT

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

    PROCEDURE:   mvn_swe_hskplot
    PURPOSE:
      Plots time series summary plots of SWEA housekeeping data over arbitrarily
      long time spans.  The result is stored in TPLOT variables.

    USAGE:
      mvn_swe_hskplot, trange=trange, orbit=orbit, hsk=hsk

    INPUTS:

    KEYWORDS:

           TRANGE:       Time range over which load data.  Must have at least two
                         elements, in any format accepted by time_double().  If
                         not specified, then load data using the current timespan.

           ORBIT:        Load data by orbit number (overrides TRANGE and TIMESPAN
                         methods).

           HSK:          Restore housekeeping from this IDL save/restore file.
                         (Full path and name required.)

           VNORM:        Subtract nominal values from all housekeeping voltages and
                         divide by the nominal values (dV/V).  Combine all relative
                         voltage differences in a single panel.  Default = 1 (yes).

           RESET:        Sets common block HSK to zero.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-08-02 14:03:50 -0700 (Mon, 02 Aug 2021) $
     $LastChangedRevision: 30164 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_hskplot.pro $

    CREATED BY:    David L. Mitchell  2017-04-06

(See projects/maven/swea/mvn_swe_hskplot.pro)

## MVN_SWE_INIT

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

    PROCEDURE:   mvn_swe_init
    PURPOSE:
      Initializes SWEA common block (mvn_swe_com).

    USAGE:
      mvn_swe_init

    INPUTS:

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-03-02 11:48:36 -0800 (Tue, 02 Mar 2021) $
     $LastChangedRevision: 29728 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_init.pro $

    CREATED BY:    David L. Mitchell  02-01-15
    FILE: mvn_swe_init.pro

(See projects/maven/swea/mvn_swe_init.pro)

## MVN_SWE_KP

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

    PROCEDURE:
    	mvn_swe_kp
    PURPOSE:
    	Calculates SWEA key parameters.  The result is stored in tplot variables,
       and as a save file.
       This routine has been updated to use Version 5 of the CDF files.

    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	mvn_swe_kp
    INPUTS:
       None:      Uses data currently loaded into the SWEA common block.

    KEYWORDS:
       TRANGE:    Process data in this time range.

       PANS:      Named variable to return tplot variables created.

       MOM:       Calculate density using a moment.  This is the default and
                  only option for now.

       DDD:       Calculate density from 3D distributions (allows bin
                  masking).  Default is to use SPEC data.  This option fits
                  a Maxwell-Boltzmann distribution to the core and performs
                  a moment calculation for the halo.  This provides corrections
                  for both spacecraft potential and scattered photoelectrons.
                  (Currently disabled.)

       ABINS:     Anode bin mask - 16-element byte array (0 = off, 1 = on)
                  Default = replicate(1B, 16).

       DBINS:     Deflector bin mask - 6-element byte array (0 = off, 1 = on)
                  Default = replicate(1B, 6).

       OBINS:     Solid angle bin mask - 96-element byte array (0 = off, 1 = on)
                  Default = reform(ABINS # DBINS, 96).

       MASK_SC:   Mask PA bins that are blocked by the spacecraft.  This is in
                  addition to any masking specified by ABINS, DBINS, and OBINS.
                  Default = 1 (yes).

       L2ONLY:    Only process data using L2 MAG data.

       QLEVEL:    Minimum quality level for calculations.  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 for this procedure is 1B.

       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.

       SECONDARY: Estimate and remove secondary electrons.  This makes greatly
                  improved moments in the sheath.  Default is 1 (yes).
                  To disable, set this keyword to zero.

       BIAS:      Bias to add to SWEPOS potential estimates.  Default = +0.5 V.

       COMPOSITE: Try to use the composite spacecraft potential first.  If that
                  fails, then try the SWE+ method.  Default = 1 (yes).

                  Set this keyword to zero to ignore the composite potential and
                  force a SWE+ calculation.

       OUTPUT_PATH: An output_path for testing, the save file will be put into
                    OUTPUT_PATH/yyyy/mm/.  Directories are created as needed.
                    Default = root_data_dir() + 'maven/data/sci/swe/kp'.

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-30 11:35:16 -0700 (Thu, 30 May 2024) $
     $LastChangedRevision: 32662 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_kp.pro $

(See projects/maven/swea/mvn_swe_kp.pro)

## MVN_SWE_LOAD_HSK

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

    PROCEDURE:   mvn_swe_load_hsk
    PURPOSE:
      Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
      spacecraft packets).  SWEA normal housekeeping (APID 28) is decomuted
      and stored in a common block (mvn_swe_com).

    USAGE:
      mvn_swe_load_hsk, trange

    INPUTS:
           trange:        Load SWEA packets from L0 data spanning this time range.
                          (Reads multiple L0 files, if necessary.  Use MAXBYTES to
                          protect against brobdingnagian loads.)
                          OPTIONAL - recommended method is to run timespan before
                          calling this routine.

    KEYWORDS:
           FILENAME:      Full path and file name for loading data.  Can be multiple
                          files.  Takes precedence over trange, ORBIT, and LATEST.

           ORBIT:         Load SWEA data by orbit number or range of orbit numbers
                          (trange and LATEST are ignored).  Orbits are numbered using
                          the NAIF convention, where the orbit number increments at
                          periapsis.  Data are loaded from the apoapsis preceding the
                          first orbit (periapsis) number to the apoapsis following the
                          last orbit number.

           LATEST:        Ignore trange (if present), and load all data within the
                          LATEST days where data exist.  (Routine checks the database
                          to find latest L0 file.)

           CDRIFT:        Correct for spacecraft clock drift using SPICE.
                          Default = 1 (yes).

           MAXBYTES:      Maximum number of bytes to process.  Default is all data
                          within specified time range.

           BADPKT:        An array of structures providing details of bad packets.

           STATUS:        Report statistics of data actually loaded.

           SUMPLOT:       Create a summary plot of the loaded data.

           LOADONLY:      Download data but do not process.

           SPICEINIT:     Force a re-initialization of SPICE.  Use with caution!

           NOSPICE:       Do not initialize SPICE.

           NODUPE:        Filter out identical packets.  Default = 1 (yes).

           SURVEY:        If no merged file(s) exist over requested time range, then
                          look for survey-only files.  This is slow, because the
                          survey files are all located in a single directory.

           REALTIME:      Use realtime file naming convention: YYYYMMDD_HHMMSS_*_l0.dat

           VERBOSE:       Level of diagnostic message suppression.  Default = 0.  Set
                          to a higher number to see more diagnostic messages.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2019-11-18 14:25:54 -0800 (Mon, 18 Nov 2019) $
     $LastChangedRevision: 28030 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_load_hsk.pro $

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

(See projects/maven/swea/mvn_swe_load_hsk.pro)

## MVN_SWE_LOAD_L0

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

    PROCEDURE:   mvn_swe_load_l0
    PURPOSE:
      Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
      spacecraft packets).  SWEA packets are identified, decompressed if
      necessary, and decomuted.  SWEA housekeeping and data are stored in
      a common block (mvn_swe_com).

      The packets can be any combination of:

        Housekeeping:      normal rate  (APID 28)
                           fast rate    (APID A6)

        3D Distributions:  survey mode  (APID A0)
                           archive mode (APID A1)

        PAD Distributions: survey mode  (APID A2)
                           archive mode (APID A3)

        ENGY Spectra:      survey mode  (APID A4)
                           archive mode (APID A5)

      Sampling and averaging of 3D, PAD, and ENGY data are controlled by group
      and cycle parameters.  The group parameter (G = 0,1,2) sets the summing of
      adjacent energy bins.  The cycle parameter (N = 0,1,2,3,4,5) sets sampling
      of 2-second measurement cycles.  Data products are sampled every 2^N cycles.

      3D distributions are stored in 1, 2 or 4 packets, depending on the group
      parameter.  Multiple packets must be stitched together (see swe_plot_dpu).

      PAD packets have one of 3 possible lengths, depending on the group parameter.
      The PAD data array is sized to accomodate the largest packet (G = 0).  When
      energies are summed, only 1/2 or 1/4 of this data array is used.

      ENGY spectra always have 64 energy channels (G = 0).

    USAGE:
      mvn_swe_load_l0, trange

    INPUTS:
           trange:        Load SWEA packets from L0 data spanning this time range.
                          (Reads multiple L0 files, if necessary.  Use MAXBYTES to
                          protect against brobdingnagian loads.)
                          OPTIONAL - recommended method is to run timespan before
                          calling this routine.

    KEYWORDS:
           FILENAME:      Full path and file name for loading data.  Can be multiple
                          files.  Takes precedence over trange, ORBIT, and LATEST.

           ORBIT:         Load SWEA data by orbit number or range of orbit numbers
                          (trange and LATEST are ignored).  Orbits are numbered using
                          the NAIF convention, where the orbit number increments at
                          periapsis.  Data are loaded from the apoapsis preceding the
                          first orbit (periapsis) number to the apoapsis following the
                          last orbit number.

           LATEST:        Ignore trange (if present), and load all data within the
                          LATEST days where data exist.  (Routine checks the database
                          to find latest L0 file.)

           CDRIFT:        Correct for spacecraft clock drift using SPICE.
                          Default = 1 (yes).

           MAXBYTES:      Maximum number of bytes to process.  Default is all data
                          within specified time range.

           BADPKT:        An array of structures providing details of bad packets.

           STATUS:        Report statistics of data actually loaded.

           SUMPLOT:       Create a summary plot of the loaded data.

           LOADONLY:      Download data but do not process.

           SPICEINIT:     Force a re-initialization of SPICE.  Use with caution!
                             0 : ask what to do if there's a problem (default)
                             1 : reinitialize to the new time range
                             2 : extend coverage to include the new time range

           NOSPICE:       Do not initialize SPICE.  This only applies if you at
                          least have the spacecraft clock and leap seconds kernels
                          already loaded.

           NODUPE:        Filter out identical packets.  Default = 1 (yes).

           SURVEY:        If no merged file(s) exist over requested time range, then
                          look for survey-only files.  This is slow, because the
                          survey files are all located in a single directory.

           REALTIME:      Use realtime file naming convention: YYYYMMDD_HHMMSS_*_l0.dat

           VERBOSE:       Level of diagnostic message suppression.  Default = 0.  Set
                          to a higher number to see more diagnostic messages.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-03 11:58:01 -0700 (Tue, 03 Jun 2025) $
     $LastChangedRevision: 33363 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_load_l0.pro $

    CREATED BY:    David L. Mitchell  04-25-13
    FILE: mvn_swe_load_l0.pro

(See projects/maven/swea/mvn_swe_load_l0.pro)

## MVN_SWE_LOAD_L2

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

    PROCEDURE:   mvn_swe_load_l2
    PURPOSE:
      Reads in MAVEN SWEA Level 2 telemetry files (CDF format).  Data are stored in
      a common block (mvn_swe_com).

      This routine can load Versions 4 and 5 of the L2 files.

      SWEA data products are:

        APID       Product Name		Product Description*
      --------------------------------------------------------------------------------
         a0          svy3d             3D distributions (64E x 16A x 6D), survey
         a1          arc3d             3D distributions (64E x 16A x 6D), archive
         a2          svypad            PAD distributions (64E x 16P), survey
         a3          arcpad            PAD distributions (64E x 16P), archive
         a4          svyspec           SPEC distributions (64E), survey
      --------------------------------------------------------------------------------
        * Array dimensions are those of the data product, which are fixed.  Data can
          be averaged in groups of 1, 2, or 4 adjacent energy channels, depending on
          SWEA's telemetry allocation.  Archive (burst) data have the least averaging.
          Averaged channels are duplicated so that there's always 64 energy channels,
          while normalization is maintained so that integrals (summations) over energy
          come out correct.

          The 3D and PAD data are never averaged over angle.  PAD data are great-circle
          cuts through the 3D data, designed to maximize pitch angle coverage.  SPEC
          data are weighted sums over the field of view, with angular weighting factors
          that mimic a moment calculation.

    USAGE:
      mvn_swe_load_l2, trange

    EXAMPLES:
      mvn_swe_load_l2, status=stat  ;  Load data based on the value of TRANGE_FULL in
                          the tplot common block.  Load all available APID's: a0, a1,
                          a2, a3, a4.  Return the status of all data types via keyword.

      mvn_swe_load_l2, apid=['a2']  ;  Load only PAD survey data.

      mvn_swe_load_l2, prod=['svypad','svyspec']  ;  Load PAD and SPEC survey data.

      mvn_swe_load_l2, trange, apid=['a0','a1']  ;  Load 3D survey and burst data for
                          the specified time range.

    INPUTS:
           trange:        Load SWEA packets from L2 data spanning this time range.
                          (Reads multiple L2 files, if necessary.)  This input is
                          not needed if you first call timespan.

    KEYWORDS:
           FILENAME:      Full path and file name for loading data.  Can be multiple
                          files.  Takes precedence over trange, ORBIT, and LATEST.

           LATEST:        Ignore trange (if present), and load all data within the
                          LATEST days leading up to the current date.

           APID:          String array specifying which APID's to load.  Default is to
                          load all APID's: ['a0','a1','a2','a3','a4'].  Loading APID a4
                          (svyspec) is required, so you will always get it, even if you
                          don't request it.

           PROD:          Alternate method for specifying which data types to load.
                          String array specifying which data products to load.
                          Default is to load all products:
                              ['svy3d','arc3d','svypad','arcpad','svyspec'].

                          The svyspec product is required (see above).

           STATUS:        Return the status of what was actually loaded: APIDs,
                          product names, numbers of packets, and time coverages.

           SUMPLOT:       Create a summary plot of the loaded data.

           LOADONLY:      Download data but do not process.

           SPICEINIT:     Force a re-initialization of SPICE.  Use with caution!
                             0 : ask what to do if there's a problem (default)
                             1 : reinitialize to the new time range
                             2 : extend coverage to include the new time range

                          Best practice is to initialize and manage SPICE outside
                          of this routine.

           NOSPICE:       Disable SPICEINIT and do not initialize SPICE.

           NOERASE:       If set, do not clear the SWEA common block.  Allows
                          sequential loading.

           SILENT:        Shhhh.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-04-29 16:43:27 -0700 (Mon, 29 Apr 2024) $
     $LastChangedRevision: 32540 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_load_l2.pro $

    CREATED BY:    David L. Mitchell  02-02-15
    FILE: mvn_swe_load_l2.pro

(See projects/maven/swea/mvn_swe_load_l2.pro)

## MVN_SWE_LOWE_MASK

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

    PROCEDURE:   mvn_swe_lowe_mask
    PURPOSE:
      Masks data affected by the sporadic low energy suppression anomaly.  The affected spectra
      are stored in a database.  This routine checks data times against that database and masks
      affected spectra with NaN's below 28 eV.  Works for all SWEA data types.  Also works for
      TPLOT variables of the form:

          {x:[time], y:[time,energy], v:[energy]}

      or

          {x:[time], y:[time]}.

      First anomalous spectrum: 2018-12-08/05:27:44
      Last anomalous spectrum: 2019-11-30/23:55:42
      Total number of anomalous spectra: 54530

      THIS ROUTINE IS NOW OBSOLETE.  It has been replaced by mvn_swe_set_quality.pro.

    USAGE:
      mvn_swe_lowe_mask, data

    INPUTS:
             data:       SWEA data structure (SPEC, PAD, or 3D).
                         Can also be a TPLOT variable.  In this case, tagname 'v', if present,
                         is interpreted as energy.

    KEYWORDS:
             BADVAL:     Value to mask anomalous data with.  Default = NaN.

             ALLBAD:     Mask all low energy channels as bad.

             STATUS:     Return the current coverage and return.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-08-25 08:40:53 -0700 (Fri, 25 Aug 2023) $
     $LastChangedRevision: 32064 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_lowe_mask.pro $

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

(See projects/maven/swea/mvn_swe_lowe_mask.pro)

## MVN_SWE_LPW_SCPOT

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

     PROCEDURE:
           mvn_swe_lpw_scpot
     PURPOSE:

           !!! This routine could take a very long time to generate the data !!!
           !!! To load pre-generated data quickly, use 'mvn_swe_lpw_scpot_restore' !!!

           Empirically derives spacecraft potentials using SWEA/STA and LPW.
           Inflection points in LPW I-V curves are tuned to positive and negative
           spacecraft potentials estimated from SWEA/STA energy spectra
           (mvn_swe_sc_pot, mvn_swe_sc_negpot, mvn_sta_scpot_load).

           Does not work in shadow.

           For more information, see
           http://research.ssl.berkeley.edu/~haraday/tools/mvn_swe_lpw_scpot.pdf

     CALLING SEQUENCE:
           timespan,'16-01-01',14   ;- make sure to set a long time range
           mvn_swe_lpw_scpot
     OUTPUT TPLOT VARIABLES:
           mvn_swe_lpw_scpot :     best-estimate scpot data
                                   (currently "mvn_swe_lpw_scpot_pol")
           mvn_swe_lpw_scpot_lin : spacecraft potentials derived from
                                   linear fitting of Vswe v. -Vinfl
           mvn_swe_lpw_scpot_pol : spacecraft potentials derived from
                                   2nd-order polynomial fitting of Vswe v. -Vinfl
           mvn_swe_lpw_scpot_pow : (obsolete)
     KEYWORDS:
           trange: time range
           norbwin: odd number of orbits used for Vswe-Vinfl fitting (Def. 37)
           minndata: minimum number of data points for Vswe-Vinfl fitting
                     (Def. 1e4)
           maxgap: maximum time gap allowed for interpolation (Def. 257)
           plot: if set, plot the time series and fitting
           noload: if set, use pre-existing input tplot variables:
                   'swe_pos', 'mvn_lpw_swp1_IV'
           vrinfl: voltage range for searching the inflection point
                   (Def. [-15,18])
           ntsmo: time smooth width (Def. 3)
     NOTES:
           1) The data quality are not good before 2015-01-24.
           2) The peak fitting algorithm sometimes breaks down
              when multiple peaks are present in dI/dV curves.
              Check the quality flag: mvn_lpw_swp1_IV_vinfl_qflag
                                      1 = good, 0 = bad
              As a rule of thumb, the quality is generally good if flag > 0.8
              You may need caution if 0.5 < flag < 0.8 (check the consistency with SWEA spectra)
           3) Short time scale variations will be smoothed out by default.
              Setting ntsmo=1 will improve the time resolution
              at the expense of better statistics.
           4) Potential values between 0 and +3 V are interpolated
              - they cannot be verified by SWEA measurements
     CREATED BY:
           Yuki Harada on 2016-02-29
           Major update on 2017-07-24 - incl. negative pot

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-07-26 13:45:34 -0700 (Fri, 26 Jul 2024) $
     $LastChangedRevision: 32769 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_lpw_scpot.pro $

(See projects/maven/swea/mvn_swe_lpw_scpot.pro)

## MVN_SWE_LPW_SCPOT_RESTORE

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

    PROCEDURE:   mvn_swe_lpw_scpot_restore
    PURPOSE:
      Reads in scpot data precalculated by mvn_swe_lpw_scpot
      and stored in a tplot save/restore file.

           For more information, see
           http://research.ssl.berkeley.edu/~haraday/tools/mvn_swe_lpw_scpot.pdf

    USAGE:
      timespan,'2016-01-01',2
      mvn_swe_lpw_scpot_restore

     NOTES:
           1) The data quality are not good before 2015-01-24.
           2) The peak fitting algorithm sometimes breaks down
              when multiple peaks are present in dI/dV curves.
              Check the quality flag: mvn_lpw_swp1_IV_vinfl_qflag
                                      1 = good, 0 = bad
              As a rule of thumb, the data quality is generally good if flag > 0.8
              You may need caution if 0.5 < flag < 0.8 (check the consistency with SWEA spectra)
           3) Short time scale variations will be smoothed out by default
           4) Potential values between 0 and +3 V are interpolated
              - they cannot be verified by SWEA measurements

    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 pad data by orbit number.

           LOADONLY:      Download but do not restore any pad data.

     $LastChangedBy: haraday $
     $LastChangedDate: 2017-07-28 07:16:06 -0700 (Fri, 28 Jul 2017) $
     $LastChangedRevision: 23717 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_lpw_scpot_restore.pro $

    CREATED BY:    Yuki Harada  03-24-16
    FILE: mvn_swe_lpw_scpot_restore.pro

(See projects/maven/swea/mvn_swe_lpw_scpot_restore.pro)

## MVN_SWE_LPW_SCPOT_SAVE

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

    PROCEDURE:   mvn_swe_lpw_scpot_save
    PURPOSE:

    USAGE:
      mvn_swe_lpw_scpot_save, start_day=start_day, ndays=ndays

    INPUTS:
           None

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

           ndays:         Number of dates to process.
                          Default = 7

    NOTES:
           mvn_swe_lpw_scpot uses a long span of data.
           For efficient processing, this save routine first loads the entire data,
           and then split and save them into one-day files.

     $LastChangedBy: haraday $
     $LastChangedDate: 2017-09-07 09:29:15 -0700 (Thu, 07 Sep 2017) $
     $LastChangedRevision: 23903 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_lpw_scpot_save.pro $

    CREATED BY:    Yuki Harada  03-04-16
    FILE: mvn_swe_lpw_scpot_save.pro

(See projects/maven/swea/mvn_swe_lpw_scpot_save.pro)

## MVN_SWE_MAGDIR

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

    PROCEDURE:   mvn_swe_magdir
    PURPOSE:
      Converts magnetic field azimuth and elevation bytes from PAD packets
      (A2 and A3) into azimuth and elevation in radians.

    USAGE:
      mvn_swe_magdir, iBaz, jBel, Baz, Bel

    INPUTS:
           time:     Packet time.  Used to correct for MICD error when needed.

           iBaz:     Azimuth byte in PAD packet.

           jBel:     Elevation byte in PAD packet.

    OUTPUTS:
           Baz:      Magnetic field azimuth in radians.  SWEA coordinates.

           Bel:      Magnetic field azimuth in radians.  SWEA coordinates.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-07-01 11:21:18 -0700 (Wed, 01 Jul 2020) $
     $LastChangedRevision: 28836 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_magdir.pro $

    CREATED BY:    David L. Mitchell  09/18/13

(See projects/maven/swea/mvn_swe_magdir.pro)

## MVN_SWE_MAKECDF_3D

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

     NAME:
       MVN_SWE_MAKECDF_3D
     SYNTAX:
    	MVN_SWEA_MAKECDF_3D, DATA, FILE = FILE, VERSION = VERSION
     PURPOSE:
    	Routine to produce CDF file from SWEA 3D data structures
       This routine has been updated to produce Version 5 of the CDF files.
       Version 5 is backward compatible with the version 4 reader.

     INPUTS:
       DATA: Structure with which to populate the CDF file
             (nominally created by mvn_swe_get3d.pro)
     OUTPUT:
       CDF file
     KEYWORDS:
       FILE: full file name of the output file - only used for testing
             if not specified (usually won't be), the program creates the appropriate filename
       VERSION: integer; software version
              - read from common block (SWE_CFG) defined in mvn_swe_calib.pro
              - keyword no longer needed (but kept for compatibility)
     HISTORY:
       Created by Matt Fillingim (with code stolen from JH and RL)
       Added directory keyword, and deletion of old files, jmm, 2014-11-14
       Read version number from common block; MOF: 2015-01-30
       ISTP compliance scrub; DLM: 2016-04-08
       Code for data version 5; DLM: 2023-08
     VERSION:
       $LastChangedBy: dmitchell $
       $LastChangedDate: 2024-01-14 17:10:01 -0800 (Sun, 14 Jan 2024) $
       $LastChangedRevision: 32362 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_makecdf_3d.pro $

(See projects/maven/swea/mvn_swe_makecdf_3d.pro)

## MVN_SWE_MAKECDF_PAD

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

     NAME:
       MVN_SWE_MAKECDF_PAD
     SYNTAX:
       MVN_SWEA_MAKECDF_PAD, DATA, FILE = FILE, VERSION = VERSION
     PURPOSE:
       Routine to produce CDF file from SWEA pad data structures
       This routine has been updated to produce Version 5 of the CDF files.
       Version 5 is backward compatible with the version 4 reader.

     INPUT:
       DATA: Structure with which to populate the CDF file
             (nominally created by mvn_swe_getpad.pro)
     OUTPUT:
       CDF file
     KEYWORDS:
       FILE: full file name of the output file - only used for testing
             if not specified (usually won't be), the program creates the appropriate filename
       VERSION: integer; software version
              - read from common block (SWE_CFG) defined in mvn_swe_calib.pro
              - keyword no longer needed (but kept for compatibility)
       L2_ONLY: only create cdf if L2 MAG data are available.
     HISTORY:
       Created by Matt Fillingim (with code stolen from JH and RL)
       Added directory keyword, jmm, 2104-11-14
       Read version number from common block; MOF: 2015-01-30
       ISTP compliance scrub; DLM: 2016-04-08
       Development code for data version 5; DLM: 2023-08
     VERSION:
       $LastChangedBy: dmitchell $
       $LastChangedDate: 2024-01-14 17:10:01 -0800 (Sun, 14 Jan 2024) $
       $LastChangedRevision: 32362 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_makecdf_pad.pro $

(See projects/maven/swea/mvn_swe_makecdf_pad.pro)

## MVN_SWE_MAKECDF_SPEC

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

     NAME:
       MVN_SWE_MAKECDF_SPEC
     SYNTAX:
       MVN_SWE_MAKECDF_SPEC, DATA, FILE = FILE, VERSION = VERSION
     PURPOSE:
       Routine to produce CDF file from SWEA spec data structures.
       This routine has been updated to produce Version 5 of the CDF files.
       Version 5 is backward compatible with the version 4 reader.

     INPUT:
       DATA: Structure with which to populate the CDF file
             (nominally created by mvn_swe_getspec.pro)
     OUTPUT:
       CDF file
     KEYWORDS:
       FILE: full name of the output file - only used for testing
             if not specified (usually won't be), the program creates the appropriate filename
       VERSION: integer; software version
              - read from common block (SWE_CFG) defined in mvn_swe_calib.pro
              - keyword no longer need (but kept for compatibility)
     HISTORY:
       created by Matt Fillingim (with code stolen from JH and RL)
       Added directory keyword, and deletion of old files, jmm, 2014-11-14
       Read version number from common block; MOF: 2015-01-30
       ISTP compliance scrub; DLM: 2016-04-08
       Code for data version 5; DLM: 2023-08
     VERSION:
       $LastChangedBy: dmitchell $
       $LastChangedDate: 2024-01-14 17:10:01 -0800 (Sun, 14 Jan 2024) $
       $LastChangedRevision: 32362 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_makecdf_spec.pro $

(See projects/maven/swea/mvn_swe_makecdf_spec.pro)

## MVN_SWE_MAKEFPAD

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

    PROCEDURE:   mvn_swe_makefpad
    PURPOSE:
      Constructs Hires PAD data structures from raw data.

    USAGE:
      mvn_swe_makefpad

    INPUTS:

    KEYWORDS:

           UNITS:    Convert data to these units.  Default = 'eflux'.

           TPLOT:    Make tplot variables.

           MERGE:    If TPLOT is set, then create normal-resolution
                     PAD spectrograms at the same energies and merge
                     with the high-resolution data.  Set this keyword
                     to the desired time range, or just set it to 1
                     and the routine will choose a reasonable time
                     range that encompasses all the hires data.

           PANS:     Returns names of any tplot variables.

           PFILE:    Name of an IDL save file for loading the hires PAD
                     data structures: swe_fpad, swe_fpad_arc.

           SFILE:    Name of an IDL save file for storing the hires PAD
                     data structure: swe_fpad, swe_fpad_arc.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 16:20:25 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33414 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_makefpad.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_makespec.pro

(See projects/maven/swea/mvn_swe_makefpad.pro)

## MVN_SWE_MAKESPEC

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

    PROCEDURE:   mvn_swe_makespec
    PURPOSE:
      Constructs ENGY data structure from raw data.

    USAGE:
      mvn_swe_makespec

    INPUTS:

    KEYWORDS:

           SUM:      Force sum mode for A4 and A5.  Not needed for EM or for FM post ATLO.
                     Default = get mode from packet.

           UNITS:    Convert data to these units.  Default = 'eflux'.

           TPLOT:    Make a energy-time spectrogram and store in tplot.

           SFLG:     If TPLOT is set, then this controls whether the panel
                     is a color spectrogram or stacked line plots.
                     Default = 1 (color spectrogram).

           PAN:      Returns the name of the tplot variable.

           LUT:      Do not recalculate the LUT.  Instead, use these values.  Must
                     have the same number of elements as SPEC.  This allows the user
                     to use custom settings in mvn_swe_getlut to handle the presence
                     of hires data.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-19 14:46:22 -0700 (Thu, 19 Jun 2025) $
     $LastChangedRevision: 33394 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_makespec.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_makespec.pro

(See projects/maven/swea/mvn_swe_makespec.pro)

## MVN_SWE_MCPCAL

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

    PROCEDURE:   mvn_swe_mcpcal
    PURPOSE:
      Analyzes in-flight MCP calibration data to estimate the optimal
      MCP bias value.  Returns the best value in decimal and hex.

    USAGE:
      mvn_swe_mcpcal, trange

    INPUTS:
         trange:          Time range bracketing calibration sequence.

    KEYWORDS:

         SCP:             Spacecraft potential (volts).  Assumes same potential
                          across calibration sequence.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-08-15 17:53:12 -0700 (Tue, 15 Aug 2017) $
     $LastChangedRevision: 23798 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_mcpcal.pro $

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

(See projects/maven/swea/mvn_swe_mcpcal.pro)

## MVN_SWE_N1D

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

    PROCEDURE:
    	mvn_swe_n1d
    PURPOSE:
    	Determines density and temperature moments from 1D energy spectra.
    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	mvn_swe_n1d
    INPUTS:
    KEYWORDS:
       PANS:      Named variable to return tplot panels created.

       DDD:       Calculate density from 3D distributions (allows bin
                  masking).  Typically lower cadence and coarser energy
                  resolution.

       ABINS:     Anode bin mask -> 16 elements (0 = off, 1 = on)
                  Default = replicate(1,16)

       DBINS:     Deflector bin mask -> 6 elements (0 = off, 1 = on)
                  Default = replicate(1,6)

       OBINS:     3D solid angle bin mask -> 96 elements (0 = off, 1 = on)
                  Default = reform(ABINS # DBINS)

       MASK_SC:   Mask the spacecraft blockage.  This is in addition to any
                  masking defined by the ABINS, DBINS, and OBINS.
                  Default = 1 (yes).  Set this to 0 to disable and use the
                  above 3 keywords only.

       MOM:       Calculate 1-dimensional moments for density and temperature.
                  Default = 1 (use moments).

       MB:        Fit a Maxwell-Boltzmann distribution to the core to determine
                  density and temperature.  Use a moment calculation to determine
                  the density of the halo.  The density is the sum of the core
                  and halo densities.  The temperature is that of the core alone.
                  This only makes sense in the upstream solar wind.
                  Default = 0 (use moments).

       MINDEN:    Smallest reliable density (cm-3).  Default = 0.08

       ERANGE:    Restrict calculation to this energy range.

       SECONDARY: Estimate and remove secondary electrons before calculating
                  moments.  See mvn_swe_secondary for details.

       RESULT:    Named variable to hold the result.

       QLEVEL:    Minimum quality level for calculating moments.  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.

       TRANGE:    Process data over this time range.

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-11 12:16:34 -0700 (Wed, 11 Jun 2025) $
     $LastChangedRevision: 33376 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_n1d.pro $

(See projects/maven/swea/mvn_swe_n1d.pro)

## MVN_SWE_N3D

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

    PROCEDURE:
    	mvn_swe_n3d
    PURPOSE:
    	Determines density from a 3D distribution.  Adapted from McFadden's n_3d.pro.
    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	mvn_swe_n3d
    INPUTS:
    KEYWORDS:

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-06-23 12:34:13 -0700 (Fri, 23 Jun 2023) $
     $LastChangedRevision: 31909 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_n3d.pro $

(See projects/maven/swea/mvn_swe_n3d.pro)

## MVN_SWE_PADLUT

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

    PROCEDURE:   mvn_swe_padlut
    PURPOSE:
      Calculates the pitch angle sorting look up table.

    USAGE:
      mvn_swe_padlut, lut=lut

    INPUTS:

    KEYWORDS:

           DLAT:        Latitude range of each elevation bin (deg).  This depends
                        on the sweep table.

                            Default at launch is 22.5 deg.
                            Actual value is closer to 20 deg.

           LUT:         Named variable to hold the LUT.

           DOPLOT:      Plot the result.

           PRINTAB:     Print the result.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-03-25 11:27:57 -0700 (Tue, 25 Mar 2014) $
     $LastChangedRevision: 14671 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_padlut.pro $

    CREATED BY:    David L. Mitchell  03-17-14
    FILE: mvn_swe_padlut.pro

(See projects/maven/swea/mvn_swe_padlut.pro)

## MVN_SWE_PADMAP

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

    FUNCTION:   mvn_swe_padmap
    PURPOSE:
      Calculates the pitch angle map for a PAD.  See mvn_swe_fovmap for the
      initialization of the SWEA field of view.

    USAGE:
      pam = mvn_swe_padmap(pkt)

    INPUTS:
           pkt  :         A raw PAD packet (APID A2 or A3).

    KEYWORDS:
           MAGF :         Magnetic field direction in SWEA coordinates.  Overrides
                          the nominal direction contained in the A2 or A3 packet.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-15 11:28:20 -0700 (Thu, 15 May 2025) $
     $LastChangedRevision: 33313 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_padmap.pro $

    CREATED BY:    David L. Mitchell  03-18-14
    FILE: mvn_swe_padmap.pro

(See projects/maven/swea/mvn_swe_padmap.pro)

## MVN_SWE_PADMAP_32HZ

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

    FUNCTION:        MVN_SWE_PADMAP_32HZ

    PURPOSE:         Maps pitch angle over the SWEA field of view with high time
                     resolution, taking into account magnetic field variations
                     during the 2-second SWEA measurement cycle.  Separate pitch
                     angle maps are calculated for each of the 64 SWEA energy
                     steps using 32-Hz MAG data.  The results are appended as new
                     tags to the PAD data structure.

                     BEWARE!  This routine requires accurate relative timing
                     between MAG and SWEA.  This is not guaranteed when using
                     preliminary data that do not have accurate corrections
                     for spacecraft clock drift.  If you get a warning message
                     about using MAG quicklook data, then you are on thin ice!
                     You might still be OK if you can verify that the MAG and
                     SWEA data were processed with the same SCLK kernel.

                     ALSO!  Since the purpose of this routine is to accurately
                     map pitch angles when the magnetic field varies on time
                     scales that are shorter than the 2-second SWEA measurement
                     cycle, you should ask yourself whether the electrons are
                     magnetized at all.  How good is the adiabatic approximation?
                     See mvn_swe_eparam.pro for more information.

    INPUTS:          PAD data structure obtained from 'mvn_swe_getpad'.

    KEYWORDS:

       FBDATA:       Tplot variable name of full resolution magnetic
                     field data.  Default = 'mvn_B_full'.

       STATUS:       Returns the calculation result
                     (Success: 1 / Failure: 0).

       MAGLEV:       Returns the MAG data level.  See warning above.
                       0 -> on-board determination or unknown
                       1 -> gains and zeroes only (quicklook)
                       2 -> fully calibrated

       L2ONLY:       Insist on using MAG L2 data.

    CREATED BY:      Takuya Hara on 2015-07-20.

    LAST MODIFICATION:
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2019-03-15 12:41:01 -0700 (Fri, 15 Mar 2019) $
     $LastChangedRevision: 26811 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_padmap_32hz.pro $

(See projects/maven/swea/mvn_swe_padmap_32hz.pro)

## MVN_SWE_PADMAP_3D

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

    PROCEDURE:
    	mvn_swe_padmap_3d

    PURPOSE:
    	Map pitch angle for PAD or 3D distributions.  In either case, you must first
       call mvn_swe_addmag to load MAG L1 or L2 data, rotate to SWEA coordinates, and
       sample at the SWEA data times.

    CALLING SEQUENCE:
    	mvn_swe_padmap_3d, data

    INPUTS:
           data:     An array of PAD or 3D structures.  For PAD structures, the
                     appropriate tags are updated.  For 3D structures, the results
                     are added as new tags.

    KEYWORDS:

    CREATED BY:      D.L. Mitchell on 2014-09-24.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2015-08-04 17:15:05 -0700 (Tue, 04 Aug 2015) $
     $LastChangedRevision: 18398 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_padmap_3d.pro $

(See projects/maven/swea/mvn_swe_padmap_3d.pro)

## MVN_SWE_PADSUM

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

    FUNCTION:   mvn_swe_padsum
    PURPOSE:
      Sums multiple PAD data structures.  This is done by summing raw counts
      corrected by deadtime and then setting dtc to unity.  Also, note that
      summed PAD's can be "blurred" by a changing magnetic field direction,
      so summing only makes sense for short intervals.  The theta, phi, and
      omega tags can be hopelessly confused if the MAG direction changes much.

    USAGE:
      padsum = mvn_swe_padsum(pad)

    INPUTS:
           pad:           An array of PAD structures to sum.

    KEYWORDS:

           QLEVEL:        Minimum quality level to sum (0-2, default=0):
                            2B = good
                            1B = uncertain
                            0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-11-13 11:17:05 -0800 (Wed, 13 Nov 2024) $
     $LastChangedRevision: 32956 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_padsum.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_padsum.pro

(See projects/maven/swea/mvn_swe_padsum.pro)

## MVN_SWE_PAD_LC_RESTORE

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

    PROCEDURE:   mvn_swe_pad_lc_restore
    PURPOSE:
      Reads in save files mvn_swe_padscore

    USAGE:
      mvn_swe_pad_lc_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_padscore data by orbit number.

           RESULT:       Hold the full structure of PAD score and
                          other parameters

           storeTPLOT:         Create tplot varibles

     $LastChangedBy: tweber $
     $LastChangedDate: 2019-10-24 09:07:47 -0700 (Thu, 24 Oct 2019) $
     $LastChangedRevision: 27928 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_pad_lc_restore.pro $

    CREATED BY:    Tristan Weber
    FILE: mvn_swe_pad_lc_restore

(See projects/maven/swea/mvn_swe_pad_lc_restore.pro)

## MVN_SWE_PAD_RESAMPLE

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

    PROCEDURE:
    	MVN_SWE_PAD_RESAMPLE

    PURPOSE:
    	Resamples the pitch angle distribution from SWEA PAD or 3D data,
       averaging the signals from bins that overlap in pitch angle space.
       Typically (and by default), pitch angle is oversampled by a factor
       of 16 to accurately treat partial overlap.

       PAD or 3D data are obtained from SWEA common block.  If you set the
       time interval, then the snapshot of the pitch angle distribution at
       the specified time is plotted.

       The result is stored in a tplot variable and can also be returned
       via keyword.

    CALLING SEQUENCE:
    	mvn_swe_pad_resample, nbins=128., erange=[100., 150.]

    INPUTS:
       trange:    Optional: Time range for resampling.  Default is to resample
                  all data (PAD or 3D, survey or burst, depending on keywords).
                  This routine might take more than 10 minutes to process PAD
                  survey data for one day, depending on your machine specs.

    KEYWORDS:
       SILENT:    Minimize to show the processing information in the terminal.

       MASK:      Mask angular bins that are blocked by the spacecraft.
                  Automatically determines whether or not the SWEA boom is
                  deployed.  Default = 1 (yes).

       NO_MASK:   If set, do not mask angular bins blocked by the spacecraft.
                  Equivalent to MASK = 0.

       STOW:      (Obsolete). Mask the angular bins whose field of view
                  is blocked before the boom deploy. --> This is now done
                  automatically.

       DDD:       Use 3D data to resample pitch angle distribution.

       PAD:       Use PAD data to resample pitch angle distribution.
                  It is the default setting.

       NBINS:     Specify resampling binning numbers. Default = 128.

       ABINS:     Specify which anode bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1,16)

       DBINS:     Specify which deflection bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1,6)

       MBINS:     Specify which solid angle bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = ABINS # DBINS

       ARCHIVE:   Use archive (burst) data, instead of survey data.

       PANS:      Named varible to hold the tplot panels created.

       WINDOW:    Set the window number to show the snapshot.  If there is
                  more than one snapshot window, then the window number
                  increments by one for each additional window.  It is the
                  user's responsibility to make sure these window(s) are
                  not already in use.

                  Default is to use the FREE keyword in WINDOW.

       RESULT:    Return the resampled pitch angle distribution data.

       UNITS:     Set the units. Default = 'EFLUX'.

       ERANGE:    Energy range over which to plot the pitch angle distribution.
                  For tplot case, default = 280 eV, based on the L0 tplot setting.

       NORMAL:    If set, then normalize the pitch angle distribution to have an
                  average value of unity at each energy.

       SNAP:      Plot a snapshot.  Default = 0 (no).

       TPLOT:     Make a tplot variable.  Default = 1 (yes).

       MAP3D:     Take into account the pitch angle width even for 3D
                  data. This keyword only works 3D data. The mapping
                  method is based on 'mvn_swe_padmap'.

       SWIA:      Resample PAD in the plasma rest frame, where electron
                  angular distributions are typically gyrotropic. Plasma bulk
                  velocity is taken from SWIA Course data.  This keyword only
                  works after loading (restoring) SWIA data.

       HIRES:     Calculate a separate pitch angle map for each energy step
                  within a sweep using 32-Hz MAG data.
                  See mvn_swe_padmap_32hz for caveats and details.

       SC_POT:    Correct for the spacecraft potential.
                  (Not completely activated yet)

       SYMDIR:    Instead of the observed magnetic field vector, use the
                  symmetry direction of the (strahl) electron distribution.
                  The symmetry direction is calculated via 'swe_3d_strahl_dir'.

       INTERPOLATE: When you try to resample the pitch angle distribtion
                    in the plasma rest frame, it calculates non-zero
                    value to have the data evaluated (interpolated) at
                    the original energy steps. This keyword is associated
                    with 'convert_vframe'.

       CUT:       Plot the pitch-angle-sorted 1d spectra for each energy step.
                  It is an optional plot.

       SPEC:      Plot the pitch-angle-selected 1d energy spectra.
                  In the default settings, 5 pitch angle bands are selected.
                     - quasi-parallel (0-30 deg),
                     - quasi-perpendicular (75-105 deg),
                     - quasi-antiparallel (150-180 deg),
                     - 2 obliquenesses (30-75, 105-150 deg).
                  It is also an optional plot.

       PSTYLE:    It means "plot style". This keyword allows
                  specification which plots you want to show.
                  Each option is described as follows:
                  - 1: Plots the snapshot(, equivalent to the "snap" keyword.)
                  - 2: Generates the tplot variable(, equivalent to the "tplot" keyword.)
                  - 4: Plots the pitch-angle-sorted 1d spectra(, equivalent to the "cut" keyword.)
                  - 8: Plots the pitch-angle-selected 1d energy spectra(, equivalent to the "spec" keyword.)
                  Note that this keyword is set bitwise, so multiple
                  effects can be achieved by adding values together. For
                  example, to plot the snapshot (value 1) and to generate
                  the tplot variable (value 2), set the PSTYLE keyword to
                  1+2, or 3. This basic idea is same as that
                  [x][y][z]style keyword included in default PLOT options.

    CREATED BY:      Takuya Hara on 2014-09-24.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 16:19:42 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33412 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_pad_resample.pro $

(See projects/maven/swea/mvn_swe_pad_resample.pro)

## MVN_SWE_PAD_RESTORE

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

    PROCEDURE:   mvn_swe_pad_restore
    PURPOSE:
      Reads in resampled pad data (100-150 eV) precalculated by mvn_swe_pad_resample
      and stored in a tplot save/restore file.  Command line used to create the tplot
      variables was:

        mvn_swe_pad_resample, nbins=128, erange=[100.,150.], /norm, /mask

      Can also be used to restore resampled 2D energy-pitch angle data.  In this case,
      use the FULL and PAD keywords.  Note that 2D pad data consume up to 375 MB/date,
      so use these keywords with caution.

    USAGE:
      mvn_swe_pad_restore, trange

    INPUTS:
           trange:        Restore data over this time range.  If not specified, then
                          uses the current tplot range.

    KEYWORDS:
           ORBIT:         Restore pad data by orbit number.

           LOADONLY:      Download but do not restore any pad data.

           UNNORM:        Unnormalize the color code.  (Only applies to single-energy
                          100-150-eV pad data.  Full 2D pad data are not normalized
                          in the first place.)

           FULL:          Restore the resampled 2D energy-pitch angle data, instead
                          of just the 100-150-eV range.  Must be used with keyword PAD.

           PAD:           Named variable to hold the restored 2D energy-pitch angle
                          data.  Must be used with keyword FULL.

           L2ONLY:        Insist that MAG L2 data were used for resampling.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-04-20 11:00:34 -0700 (Tue, 20 Apr 2021) $
     $LastChangedRevision: 29892 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_pad_restore.pro $

    CREATED BY:    David L. Mitchell  04-25-13
    FILE: mvn_swe_pad_restore.pro

(See projects/maven/swea/mvn_swe_pad_restore.pro)

## MVN_SWE_PAD_SAVE

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

    PROCEDURE:   mvn_swe_pad_save
    PURPOSE:
      Calculates resampled pad data (100-150 eV) using mvn_swe_pad_resample and
      saves in a tplot save/restore file.  Command line used to create the tplot
      variables is:

        mvn_swe_pad_resample, nbins=128, erange=[100.,150.], /norm, /mask

    USAGE:
      mvn_swe_pad_save, start_day, interval, ndays

    INPUTS:
           None:          Default is to process data currently loaded into memory.

    KEYWORDS:
           start_day:     Restore data over this time range.  If not specified, then
                          use the currently loaded data.

           interval:      If start_day is defined and ndays > 1, then this is the number
                          of days to skip before loading the next date.  (Only useful
                          for poor-man's parallel processing.)  Default = 1

           ndays:         Number of dates to process, each separated by interval.
                          Default = 1

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-05-14 16:09:52 -0700 (Fri, 14 May 2021) $
     $LastChangedRevision: 29963 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_pad_save.pro $

    CREATED BY:    David L. Mitchell  04-25-13
    FILE: mvn_swe_pad_save.pro

(See projects/maven/swea/mvn_swe_pad_save.pro)

## MVN_SWE_POT_CONVE

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

    PROCEDURE:
       mvn_swe_pot_conve

    PURPOSE:
       correct for potential and then convert to SWEA original resolution

    AUTHOR:
       Shaosui Xu

    CALLING SEQUENCE:

    INPUTS:

       INEN: The energy array corresponding to the input energy spectrum

       INSPEC: Input electron energy spectrum

       POT: Specify the potential to be corrected

    KEYWORDS:

       none

    OUTPUTS:

       OUTEN: The energy array corresponding to the input energy spectrum,
              currently set to be SWEA energy resolution

       OUTSPEC: The converted energy spectrum

     $LastChangedBy: xussui_lap $
     $LastChangedDate: 2016-06-22 17:23:44 -0700 (Wed, 22 Jun 2016) $
     $LastChangedRevision: 21353 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_pot_conve.pro $

    CREATED BY:    Shaosui Xu  06-22-16

(See projects/maven/swea/mvn_swe_pot_conve.pro)

## MVN_SWE_QL

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

    PROCEDURE:   mvn_swe_ql
    PURPOSE:
      Creates SWEA TPLOT variables for QuickLook plots.

    USAGE:
      mvn_swe_ql

    INPUTS:

    KEYWORDS:

           NAMES:        TPLOT variables names created.
                         Returns 0 if no variables are created.

           PAD_E:        Energy for plotting PAD's.  Default = 280 eV.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-12-15 13:03:20 -0800 (Tue, 15 Dec 2020) $
     $LastChangedRevision: 29494 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_ql.pro $

    CREATED BY:    David L. Mitchell  04-30-13
    FILE: mvn_swe_ql.pro
    VERSION:   1.0

(See projects/maven/swea/mvn_swe_ql.pro)

## MVN_SWE_READCDF_3D

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

     NAME:
       MVN_SWE_READCDF_3D
     SYNTAX:
       MVN_SWE_READCDF_3D, INFILE, STRUCTURE
     PURPOSE:
       Routine to read CDF file from mvn_swe_makecdf_3d.pro
       Reads both Version 4 and 5 CDF files.

     INPUTS:
       INFILE: CDF file name to read
               (nominally created by mvn_swe_makecdf_3d.pro)
     OUTPUT:
       STRUCTURE: IDL data structure
     KEYWORDS:
       OUTFILE: Output file name
     HISTORY:
       Created by Matt Fillingim
       Code for data version 5; DLM: 2023-08
     VERSION:
       $LastChangedBy: dmitchell $
       $LastChangedDate: 2024-01-14 17:10:01 -0800 (Sun, 14 Jan 2024) $
       $LastChangedRevision: 32362 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_readcdf_3d.pro $

(See projects/maven/swea/mvn_swe_readcdf_3d.pro)

## MVN_SWE_READCDF_PAD

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

     NAME:
       MVN_SWE_READCDF_PAD
     SYNTAX:
       MVN_SWE_READCDF_PAD, INFILE, STRUCTURE
     PURPOSE:
       Routine to read CDF file from mvn_swe_makecdf_pad.pro
       Reads both Version 4 and 5 CDF files.

     INPUTS:
       INFILE: CDF file name to read
               (nominally created by mvn_swe_makecdf_pad.pro)
     OUTPUT:
       STRUCTURE: IDL data structure
     KEYWORDS:
       OUTFILE: Output file name
     HISTORY:
       Created by Matt Fillingim
       Code for data version 5; DLM: 2023-08
     VERSION:
       $LastChangedBy: dmitchell $
       $LastChangedDate: 2024-01-14 17:10:01 -0800 (Sun, 14 Jan 2024) $
       $LastChangedRevision: 32362 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_readcdf_pad.pro $

(See projects/maven/swea/mvn_swe_readcdf_pad.pro)

## MVN_SWE_READCDF_SPEC

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

     NAME:
       MVN_SWE_READCDF_SPEC
     SYNTAX:
    	MVN_SWE_READCDF_SPEC, INFILE, STRUCTURE
     PURPOSE:
    	Routine to read CDF file from mvn_swe_makecdf_spec.pro
       Reads both Version 4 and 5 CDF files.

     INPUTS:
       INFILE: CDF file name to read
               (nominally created by mvn_swe_makecdf_spec.pro)
     OUTPUT:
       STRUCTURE: IDL data structure
     KEYWORDS:
       OUTFILE: Output file name
     HISTORY:
       Created by Matt Fillingim
       Code for data version 5; DLM: 2023-08
     VERSION:
       $LastChangedBy: dmitchell $
       $LastChangedDate: 2024-01-14 17:10:01 -0800 (Sun, 14 Jan 2024) $
       $LastChangedRevision: 32362 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_readcdf_spec.pro $

(See projects/maven/swea/mvn_swe_readcdf_spec.pro)

## MVN_SWE_READ_HSK

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

    PROCEDURE:   mvn_swe_read_hsk
    PURPOSE:
      Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
      spacecraft packets).  SWEA normal housekeeping packets (APID 28)
      are identified and decomuted.  Data are stored in a common block
      (mvn_swe_com).

    USAGE:
      mvn_swe_read_hsk, filename

    INPUTS:
           filename:      The full filename (including path) of a binary file containing
                          zero or more SWEA APID's.  This file can contain compressed
                          packets.

    KEYWORDS:
           TRANGE:        Only keep packets within this time range.

           CDRIFT:        Correct for spacecraft clock drift using SPICE.
                          Default = 0 (no).

           MAXBYTES:      Maximum number of bytes to process.  Default is entire file.

           BADPKT:        An array of structures providing details of bad packets.

           APPEND:        Append data to any previously loaded data.

           VERBOSE:       If set, then print diagnostic information to stdout.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-08-02 11:13:42 -0700 (Wed, 02 Aug 2023) $
     $LastChangedRevision: 31974 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_read_hsk.pro $

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

(See projects/maven/swea/mvn_swe_read_hsk.pro)

## MVN_SWE_READ_L0

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

    PROCEDURE:   mvn_swe_read_l0
    PURPOSE:
      Reads in MAVEN Level 0 telemetry files (PFDPU packets wrapped in
      spacecraft packets).  SWEA packets are identified, decompressed if
      necessary, and decomuted.  SWEA housekeeping and data are stored in
      a common block (mvn_swe_com).

      The packets can be any combination of:

        Housekeeping:      normal rate  (APID 28)
                           fast rate    (APID A6)
                           pfp analog   (APID 23)

        3D Distributions:  survey mode  (APID A0)
                           archive mode (APID A1)

        PAD Distributions: survey mode  (APID A2)
                           archive mode (APID A3)

        ENGY Spectra:      survey mode  (APID A4)
                           archive mode (APID A5)

      Sampling and averaging of 3D, PAD, and ENGY data are controlled by group
      and cycle parameters.  The group parameter (G = 0,1,2) sets the summing of
      adjacent energy bins.  The cycle parameter (N = 0,1,2,3,4,5) sets sampling
      of 2-second measurement cycles.  Data products are sampled every 2^N cycles.

      3D distributions are stored in 1, 2 or 4 packets, depending on the group
      parameter.  Multiple packets must be stitched together (see swe_3d_stitch).

      PAD packets have one of 3 possible lengths, depending on the group parameter.
      The PAD data array is sized to accomodate the largest packet (G = 0).  When
      energies are summed, only 1/2 or 1/4 of this data array is used.

      ENGY spectra always have 64 energy channels (G = 0).

    USAGE:
      mvn_swe_read_l0, filename

    INPUTS:
           filename:      The full filename (including path) of a binary file containing
                          zero or more SWEA APID's.  This file can contain compressed
                          packets.

    KEYWORDS:
           TRANGE:        Only keep packets within this time range.

           CDRIFT:        Correct for spacecraft clock drift using SPICE.
                          Default = 0 (no).

           MAXBYTES:      Maximum number of bytes to process.  Default is entire file.

           BADPKT:        An array of structures providing details of bad packets.

           APPEND:        Append data to any previously loaded data.

           VERBOSE:       If set, then print diagnostic information to stdout.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-01-08 16:01:00 -0800 (Mon, 08 Jan 2024) $
     $LastChangedRevision: 32336 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_read_l0.pro $

    CREATED BY:    David L. Mitchell  04-25-13
    FILE: mvn_swe_read_l0.pro

(See projects/maven/swea/mvn_swe_read_l0.pro)

## MVN_SWE_REGID_RESTORE

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

    PROCEDURE:   mvn_swe_regid_restore
    PURPOSE:
      Reads in save files mvn_swia_regid

    USAGE:
      mvn_swe_regid_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_swia_regid data by orbit number.

           RESULTS:       Hold the full structure of region id

           TPLOT:         Create tplot varible for region id "reg_id"

     $LastChangedBy: xussui $
     $LastChangedDate: 2018-07-18 12:28:53 -0700 (Wed, 18 Jul 2018) $
     $LastChangedRevision: 25488 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_regid_restore.pro $

    CREATED BY:    Shaosui Xu  11-17-17
    FILE: mvn_swe_regid_restore

(See projects/maven/swea/mvn_swe_regid_restore.pro)

## MVN_SWE_RESTORE

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

    PROCEDURE:   mvn_swe_restore
    PURPOSE:
      Restores SWEA save files and updates the SWEA common blocks.

    INPUTS:
           None.

    KEYWORDS:
           FILENAME:   Full path and name of save file.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-19 14:50:07 -0700 (Thu, 19 Jun 2025) $
     $LastChangedRevision: 33395 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_restore.pro $

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

(See projects/maven/swea/mvn_swe_restore.pro)

## MVN_SWE_SAVE

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

    PROCEDURE:   mvn_swe_save
    PURPOSE:
      Saves the SWEA common block to a save file.

    INPUTS:
           None.

    KEYWORDS:
           FILENAME:   Full path and name for save file.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-19 14:50:07 -0700 (Thu, 19 Jun 2025) $
     $LastChangedRevision: 33395 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_save.pro $

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

(See projects/maven/swea/mvn_swe_save.pro)

## MVN_SWE_SCIPLOT

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

    PROCEDURE:
    	mvn_swe_sciplot
    PURPOSE:
    	Creates a science-oriented summary plot for SWEA and MAG and optionally other
       instruments.

       Warning: This routine can consume a large amount of memory:

         SWEA + MAG : 0.6 GB/day
         SEP        : 0.2 GB/day
         SWIA       : 0.2 GB/day
         STATIC     : 3.5 GB/day
         LPW        : 0.001 GB/day
         EUV        : 0.004 GB/day
         -------------------------
          total     : 4.5 GB/day

       You'll also need memory for performing calculations on large arrays, so you
       can create a plot with all data types spanning ~1 day per 8 GB of memory.

    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	mvn_swe_sciplot
    INPUTS:
       None:      Uses data currently loaded into the SWEA common block.

    KEYWORDS:
       SUN:       Create a panel for the Sun direction in spacecraft coordinates.

       RAM:       Create a panel for the RAM direction in spacecraft coordinates.

       NADIR:     Create a panel for the Nadir direction in spacecraft coordinates.

       DATUM:     Reference surface for calculating altitude.  Can be one of
                  "sphere", "ellipsoid", "areoid", or "surface".  Passed to
                  maven_orbit_tplot.  Default = 'ellipsoid'.
                  See mvn_altitude.pro for details.

       SEP:       Include two panels for SEP data: one for ions, one for electrons.

       SWIA:      Include panels for SWIA ion density and bulk velocity (coarse
                  survey ground moments).

       STATIC:    Include two panels for STATIC data: one mass spectrum, one energy
                  spectrum.

       IV_LEVEL:  IV level for STATIC, from 0 to 4.  Values greater than zero fill
                  in background estimates from up to four different sources.
                  Currently in development.  Default = 0.

       APID:      Additional STATIC APID's to load.  (Hint: D0, D1 might be useful.)

       LPW:       Include panel for electron density from LPW data.

                  Note: if two or more of O2+, O+, and electron densities are present
                  they are combined into a single panel.

       EUV:       Include a panel for EUV data.

       SC_POT:    Include a panel for spacecraft potential.

       EPH:       Named variable to hold ephemeris data.

       LOADONLY:  Create tplot variables, but don't plot.

       PANS:      Array of tplot variables created.

       PADSMO:    Smooth the resampled PAD data in time with this smoothing interval,
                  in seconds.

       SHAPE:     Include a panel for the electron shape parameter.

       MAGFULL:   If set, then try to load full resolution (32 Hz) MAG data.
                  Default is to load 1-sec data.

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-19 14:45:39 -0700 (Thu, 19 Jun 2025) $
     $LastChangedRevision: 33393 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sciplot.pro $

(See projects/maven/swea/mvn_swe_sciplot.pro)

## MVN_SWE_SC_NEGPOT

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

    PROCEDURE:
       mvn_swe_sc_negpot

    PURPOSE:
       Estimates the negative spacecraft potential within the ionosphere
       from SWEA energy spectra.  The basic idea is to use the second
       derivative of the spectrum to find the shift of the He II features
       at 23 and 27 eV (mainly the 23 eV feature), from which then the
       negative potential can be calculated.  No attempt is made to
       estimate the potential when the spacecraft is in darkness or above
       1000 km altitude.

    AUTHOR:
       Shaosui Xu

    CALLING SEQUENCE:
       This procedure requires tplot variables "mvn_swe_shape_par, swe_a4, alt,
       sza, d2f".  If any of these variables does not exist, then this procedure
       attempts to create them using the appropriate procedures.

    INPUTS:
       none

    KEYWORDS:
    	POTENTIAL: Returns spacecraft potentials in a structure.

       FILL:      Do not fill in the common block.  Default = 0 (no).

       RESET:     Initialize the spacecraft potential, discarding all previous
                  estimates, and start fresh.

       QLEVEL:    Minimum quality level for processing.  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.

    OUTPUTS:
       None - Result is stored in the common block variables swe_sc_pot and
              mvn_swe_engy, and as the TPLOT variable 'neg_pot'.

     $LastChangedBy: xussui_lap $
     $LastChangedDate: 2025-03-13 16:36:15 -0700 (Thu, 13 Mar 2025) $
     $LastChangedRevision: 33173 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sc_negpot.pro $

(See projects/maven/swea/mvn_swe_sc_negpot.pro)

## MVN_SWE_SC_NEGPOT_TWODIR_BURST

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

    PROCEDURE:
       mvn_swe_sc_negpot_twodir_burst

    PURPOSE:
       Estimates potentials from the shift of He II features
       for both anti-parallel and parallel directions with
       SWEA PAD data. Right now it only works for burst data.

    INPUTS:
       none

    KEYWORDS:
    	POTENTIAL: Returns spacecraft potentials in a structure.

       SHADOW:    If keyword set, all the estimations outside of shadow
                  at altitudes > 800 km are set to NANs

       SWIDTH:    Field-aligned angle to calculate spectra for both
                  directions. The default value is 45 degrees.

       FILL:      Fill in the common block.  Default = 0 (no).

       RESET:     Initialize the spacecraft potential, discarding all previous
                  estimates, and start fresh.

       SCPOT:     If keyword set, it provides s/c potential estimates.
                  The default is set to be 1.

    OUTPUTS:
       None - Potential results are stored as a TPLOT variable 'negpot_pad'.
              Four additional TPLOT variables are created for diagnostics.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 16:18:35 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33411 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sc_negpot_twodir_burst.pro $

    CREATED BY:    Shaosui Xu  01-03-2017

(See projects/maven/swea/mvn_swe_sc_negpot_twodir_burst.pro)

## MVN_SWE_SC_POSPOT

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

    FUNCTION:
    	mvn_swe_sc_pospot

    PURPOSE:
    	Estimates the spacecraft potential from SWEA energy spectra.  The basic
       idea is to look for a break in the energy spectrum (sharp change in flux
       level and slope).  Works for one or more spectra.

    AUTHOR:
    	David L. Mitchell

    CALLING SEQUENCE:
    	scpot = mvn_swe_sc_pospot(engy, eflux)

    INPUTS:
       engy:      Energy array with dimensions of [n_e] or [n_e, n_t].

       eflux:     Energy flux, with dimensions of [n_e, n_t].

    KEYWORDS:
       DIAG:      A structure of diagnostic information that provides the quality
                  of the potential estimates.

    OUTPUTS:
       scpot:     An array of n_t spacecraft potentials.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-07-26 13:45:34 -0700 (Fri, 26 Jul 2024) $
     $LastChangedRevision: 32769 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sc_pospot.pro $

(See projects/maven/swea/mvn_swe_sc_pospot.pro)

## MVN_SWE_SC_POT

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

    PROCEDURE:
    	mvn_swe_sc_pot

    PURPOSE:
    	Estimates the spacecraft potential from SWEA energy spectra.  The basic
       idea is to look for a break in the energy spectrum (sharp change in flux
       level and slope).  No attempt is made to estimate the potential when the
       spacecraft is in darkness (expect negative potential) or below 250 km
       altitude (expect small or negative potential).

    AUTHOR:
    	David L. Mitchell

    CALLING SEQUENCE:
    	mvn_swe_sc_pot, potential=dat

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

    KEYWORDS:
    	POTENTIAL: Returns spacecraft potentials in a structure.

       ERANGE:    Energy range over which to search for the potential.
                  Default = [3.,30.]

       THRESH:    Threshold for the minimum slope: d(logF)/d(logE).
                  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.  Default = 1e6.

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

       BIAS:      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.

       DDD:       Use 3D data to calculate potential.  Allows bin masking,
                  but lower cadence and typically lower energy resolution.

       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).

       ANGCORR:   Angular distribution correction based on interpolated 3d data
                  to emphasize the returning photoelectrons and improve
                  the edge detection (added by Yuki Harada).

       QLEVEL:    Minimum quality level for processing.  Filters out the vast
                  majority of spectra affected by the sporadic low energy
                  anomaly below 28 eV.  The quality 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.

                  Filtering (QLEVEL > 0) is essential for removing bad s/c
                  potential estimates.  Default = 1B.

       PANS:      Named varible to hold the tplot panels created.

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

       FILL:      Do not fill in the common block.  Default = 0 (no).

       RESET:     Initialize the spacecraft potential, discarding all previous
                  estimates, and start fresh.

    OUTPUTS:
       None - Result is stored in SPEC data structure, returned via POTENTIAL
              keyword, and stored as a TPLOT variable.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-07-26 13:45:34 -0700 (Fri, 26 Jul 2024) $
     $LastChangedRevision: 32769 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sc_pot.pro $

(See projects/maven/swea/mvn_swe_sc_pot.pro)

## MVN_SWE_SECONDARY

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

    PROCEDURE:   mvn_swe_secondary
    PURPOSE:
      Estimates contamination caused by secondary electrons emitted from interior
      surfaces of the instrument.  Most secondaries that make it to the MCP are
      likely emitted from surfaces near the entrance to the hemispheres, which are
      coated with Cu2S.  Some fraction may come from the deflectors, which are
      coated with black nickel.

      Method adapted from Andreone et al., JGR Space Phys. 127, e2121JA029404 (2022).

      Primary electron weighting function (secondary yield per primary):
        Emax = 300.
        s = 1.6                       ; from experiment (Schultz+ 1996)
        s = 1.9 - 1.05*alog10(e)/3.   ; tuned to be close to Andreone+ 2022

        d(E) = exp(-(alog(E/Emax)^2.)/(2.*s*s))

        <Fp> = total(Fp(E) * d(E) * dE)  ; summed above s/c potential

      Secondary electron population has a Maxwell-Boltzmann distribution with a
      temperature that is independent of primary energy:
        E0 = 4.0                      ; from in-flight calibration (see below)
        Smax = 0.1225
        S(E) = Smax * exp(1.) * (E/E0) * exp(-(E/E0))

      Secondary electron differential flux:
        Fs = eps * <Fp> * S(E)

      The scale factor eps is of order unity.  It is used to tune the secondary
      yield to match observations.  Andreone allowed eps to be tuned separately
      for each spectrum.  In the sheath, the electron distribution can change
      significantly during the 2-second SWEA measurement cycle, so a dynamic
      correction is necessary.

      Filters are used to avoid over- and under- correction.

      Primaries impact interior surfaces to produce secondaries, so energy for
      both populations is measured in the instrument frame.

    USAGE:
      mvn_swe_secondary, data [, /tplot]   ; normal usage

      mvn_swe_secondary, config=value      ; initialize with custom parameters

    INPUTS:
           data:         Array of SPEC, PAD or 3D data structures.

    KEYWORDS:
           CONFIG:       A structure containing parameters for the yield and
                         secondary distribution functions.  This can have one
                         or more of the following tags:

                           e0  : temperature (eV) of the M-B secondary electron
                                 distribution (default = 4.0 eV, based on
                                 observations in the sheath, where the secondary
                                 population is well separated from the primary
                                 population)

                           s0  : peak value of the M-B secondary electron
                                 distribution function (default = 0.1225)

                           e1  : peak (eV) of the secondary yield function
                                 (default = 300 eV)

                           s1  : scale factor for the secondary yield
                                 (default = 0.8)

                           scl : 0 = use fixed scale factor
                                 f = dynamically adjust scale factor so that
                                     secondary flux is never more than f times
                                     the measured flux (f <= 1)

                         These values are persistent for subsequent calls.

           PARAM:        Returns the CONFIG parameter structure.

           DEFAULT:      Sets CONFIG to defaults.

           TPLOT:        Create a tplot variable.  (Only works for SPEC data.)

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-01-03 12:14:09 -0800 (Fri, 03 Jan 2025) $
     $LastChangedRevision: 33040 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_secondary.pro $

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

(See projects/maven/swea/mvn_swe_secondary.pro)

## MVN_SWE_SET_QUALITY

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

    PROCEDURE:   mvn_swe_set_quality
    PURPOSE:
      Inspects SPEC, PAD and 3D data (survey and burst) in the common block.
      Determines the time range spanned by the data, then reads in pre-determined
      quality flags from IDL save/restore files.  Fills in QUALITY information
      in the data structures.

      Quality flag definitions:

          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.

    USAGE:
      mvn_swe_set_quality

    INPUTS:
           None:          All information is obtained from the common block.

    KEYWORDS:
           TRANGE:        Time range to process.  If not set, then get time range
                          from data stored in the common block.

           MISSING:       Returns a 5-element array with the number of quality
                          flags that were NOT found in the database for each of
                          data type: 3D_SVY, 3D_ARC, PAD_SVY, PAD_ARC, SPEC.  If
                          everything works perfectly, then MISSING = [0,0,0,0,0].

           VALUE:         Set all quality flags to this value.  Must be a byte
                          integer of 0B, 1B, or 2B.

           DOPLOT:        If set, makes an energy spectrogram (SPEC) tplot panel
                          with an 'x' marking anomalous spectra (quality = 0).
                          Not recommended -- better to use the swe_quality tplot
                          variable instead.

           REFRESH:       Action to take if a quality save file is not found.
                          This keyword can have one of three integer values:

                            0 : Do nothing.  Just fill the quality flag array
                                with 1's (unknown) for all times covered by the
                                missing file.  Default.

                            1 : Attempt to create the missing file, then try to
                                load it.

                            2 : Create or recreate all files, overwriting any
                                existing file(s).

                          *** This keyword only works for authorized users! ***

           SILENT:        Shhh.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-11-13 11:16:03 -0800 (Wed, 13 Nov 2024) $
     $LastChangedRevision: 32955 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_set_quality.pro $

    CREATED BY:  David Mitchell - August 2023

(See projects/maven/swea/mvn_swe_set_quality.pro)

## MVN_SWE_SHAPE_DAILYSAVE

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

    PROCEDURE:   mvn_swe_shape_dailysave
    PURPOSE:

    USAGE:
      mvn_swe_shape_dailysave,start_day=start_day,end_day=end_day,ndays=ndays, saveflux=saveflux

    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

           saveflux:      If set to 1, will save eflux for 3 PA ranges to
                          a provided directory.
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 10:14:21 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33407 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_shape_dailysave.pro $

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

(See projects/maven/swea/mvn_swe_shape_dailysave.pro)

## MVN_SWE_SHAPE_PAR

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

    PROCEDURE:
    	mvn_swe_shape_par
    PURPOSE:
    	Calculates SWEA energy shape parameter and stores it as a TPLOT variable.
    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	mvn_swe_shape_par
    INPUTS:

    KEYWORDS:
       PANS:      Named variable to return tplot variable created.

       VAR:       Get SPEC data from tplot instead of SWEA common block.
                  In this case, you are responsible for making sure the
                  data are in units of EFLUX.  Any other units will give
                  bogus results.
                  (Set this keyword to the variable name or index.)

       KEEP_NAN:  If set, then include results for all input spectra, using
                  NaN for invalid results.  Otherwise, only valid results
                  are returned.

       TRANGE:    Process data over this time range.

       ERANGE:    If set, then calculate the shape parameter over this
                  energy range.  Default is 0-100 eV.

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-19 10:40:08 -0700 (Sun, 19 May 2024) $
     $LastChangedRevision: 32605 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_shape_par.pro $

(See projects/maven/swea/mvn_swe_shape_par.pro)

## MVN_SWE_SHAPE_PAR_PAD

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

    PROCEDURE:
       mvn_swe_shape_par_pad

    PURPOSE:

       Calculate pitch angle resolved shape parameters for loaded SWEA PAD data
       and create tplot variable "Shape_PAD"

    AUTHOR:
       Shaosui Xu

    CALLING SEQUENCE:

       Assume SWEA l0 data loaded

       If desire to correct for spacecraft potential, first run "mvn_swe_sc_pot"

    INPUTS:

       none

    KEYWORDS:

       BURST: If set to 1, then use burst data to calculate the shape parameter,
              however, not tested yet

       SPEC: A pitch angle in degrees given to average.
             PA [0,SPEC] & [(180-SPEC),180] for two directions.
             The default value is 30

       ERANGE: Shape parameter calculated based on the spectrum within this energy
               range. The default values are [20,80] eV

       MAG_GEO: A MAG structure that contains magnetic elevation angle. If not given,
                The program will load MAG data in GEO coordinates.

       POT: If set to 1, this program will correct the spacecraft potential for
            the electron energy spectrum.

    OUTPUTS:

       Tplot variable "Shape_PAD": store shape parameters for two directions, as well
           as the shape parameter for trapped population, spacecraft potentials,
           min/max pitch angle range to check if the PA coverage is enough

       Tplot variable "EFlux_ratio": store the flux ratio for two directions

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-10-24 11:30:20 -0700 (Thu, 24 Oct 2024) $
     $LastChangedRevision: 32897 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_shape_par_pad.pro $

    CREATED BY:    Shaosui Xu  06-22-16

(See projects/maven/swea/mvn_swe_shape_par_pad.pro)

## MVN_SWE_SHAPE_PAR_PAD_L2

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

    PROCEDURE:
       mvn_swe_shape_par_pad_l2

    PURPOSE:

       Calculate pitch angle resolved shape parameters for loaded SWEA L2
       PAD survey data and create tplot variable "Shape_PAD"

    AUTHOR:
       Shaosui Xu

    CALLING SEQUENCE:

       If desire to correct for spacecraft potential, first run "mvn_swe_sc_pot"

    INPUTS:

       none

    KEYWORDS:

       BURST:    If set to 1, then use burst data to calculate the shape parameter,
                 however, not tested yet

       SPEC:     A pitch angle in degrees given to average.
                 PA [0,SPEC] & [(180-SPEC),180] for two directions.
                 The default value is 30

       ERANGE:  Shape parameter calculated based on the spectrum within this energy
                range. The default values are [20,80] eV

       MIN_PAD_EFLUX: Minimum energy flux level.

       MAG_GEO: A MAG structure that contains magnetic elevation angle. If not given,
                The program will load MAG data in GEO coordinates.

       POT:     If set to 1, this program will correct the spacecraft potential for
                the electron energy spectrum.

       NSMO:    Number of spectra to average over before calculating shape parameter.
                Default = 1 (no smoothing).

       TSMO:    Boxcar smooth the PADs with this width (in seconds) before calculating
                the shape parameter.  This method is slower but handles data gaps and
                changes in instrument mode.  Takes precedence over NSMO.

    OUTPUTS:

       Tplot variable "Shape_PAD": store shape parameters for two directions, as well
           as the shape parameter for trapped population, spacecraft potentials,
           min/max pitch angle range to check if the PA coverage is enough

       Tplot variable "EFlux_ratio": store the flux ratio for two directions

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 10:14:21 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33407 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_shape_par_pad_l2.pro $

    CREATED BY:    Shaosui Xu  12-08-16

(See projects/maven/swea/mvn_swe_shape_par_pad_l2.pro)

## MVN_SWE_SHAPE_PAR_PAD_RESTORE

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

    PROCEDURE:   mvn_swe_shape_par_pad_restore
    PURPOSE:
      Reads in tplot save/restore files swe_shape_par_pad
      Command line used to create the tplot

    USAGE:
      mvn_swe_shape_par_pad_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 pad data by orbit number.

           LOADONLY:      Download but do not restore any pad data.

     $LastChangedBy: xussui_lap $
     $LastChangedDate: 2016-10-11 14:11:51 -0700 (Tue, 11 Oct 2016) $
     $LastChangedRevision: 22085 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_shape_par_pad_restore.pro $

    CREATED BY:    Shaosui Xu  10-11-16
    FILE: mvn_swe_shape_par_pad_restore.pro

(See projects/maven/swea/mvn_swe_shape_par_pad_restore.pro)

## MVN_SWE_SHAPE_RESTORE

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

    PROCEDURE:   mvn_swe_shape_restore
    PURPOSE:
      Reads in save files swe_shape_par_pad

    USAGE:
      mvn_swe_shape_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 shape_par_pad data by orbit number.

           RESULTS:       Hold the full structure of shape parameters and other parameters

           TPLOT:         Create tplot varible for two-stream shape parameter, being
                          stored as tplot variable "Shape_PAD" and "rat_a2t"

           PARNG:         Shape parameter calculated based on 30, 45, and 60 deg,
                          corresponding to PARNG=1,2,3. Default is PA=45

     $LastChangedBy: xussui_lap $
     $LastChangedDate: 2024-09-17 15:35:33 -0700 (Tue, 17 Sep 2024) $
     $LastChangedRevision: 32842 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_shape_restore.pro $

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

(See projects/maven/swea/mvn_swe_shape_restore.pro)

## MVN_SWE_SLICE2D_SNAP

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

    PROCEDURE:       MVN_SWE_SLICE2D_SNAP

    PURPOSE:         Plots 2D slice for the times and data type selected by cursor.
                     Hold down the left mouse button and slide for a movie effect.

    INPUTS:          None.
                     But the specified time (or [tmin, tmax]) is set, it
                     automatically show the snapshot. In this case, the
                     cursor does not appear in a tplot window.

    CAUTION:         *** !!! ***
                     The velocity estimated from the SWEA electron 3D data
                     via 'v_3d' is not likely reliable.
                     Highly recommended to use the bulk velocity
                     estimated from the other data (e.g., SWIA ion data).
                     *** !!! ***

    KEYWORDS:        All the keywords included in 'slice2d' are acceptable.

       ARCHIVE:      Returns archive distribution instead of survey.

         BURST:      Synonym for "ARCHIVE".

        WINDOW:      Specifies window number to plot.
                     A new window to show is generated as default.

         BLINE:      Shows magnetic field direction by a black solid line.

           MSO:      Rotates into the MSO coordinates (no effect on 'BV',
                     'BE', and 'perp' cuts).

         ABINS:      Specifies which azimuth anode bins to
                     include in the analysis: 0 = no, 1 = yes.
                     Default = replicate(1, 16)

         DBINS:      Specifies which deflection bins to
                     include in the analysis: 0 = no, 1 = yes.
                     Default = replicate(1, 6).

         OBINS:      Specifies which angular bins to inclue in the
                     analysis: 0 = no, 1 = yes. Default = replicate(1, 96).

       MASK_SC:      Mask solid angle bins that are blocked by the spacecraft.
                     Default = 1

       KEEPWIN:      If set, then don't close the snapshot window on exit.

           SUM:      If set, use cursor to specify time ranges for averaging.

    USAGE EXAMPLES:
             1.      ; Normal case
                     ; Uses archive data, and shows the B field direction.
                     ; Draws the X-Y plane slice in the SWEA coordinates.

                     mvn_swe_slice2d_snap, /arc, /bline, rot='xy'

             2.      ; Specified time case
                     ; Selects the time to show.

                     ctime, t ; Clicks once or twice on the tplot window.

                     ; Draws the electron velocity distribution
                     ; function in the plane perpendicular to the B field.

                     mvn_swe_slice2d_snap, t, rot='perp'

             3.      ; Advanced case
                     ; Uses 'ctime' procedure with "routine" keyword.

                     ctime, routine='mvn_swe_slice2d_snap'

    CREATED BY:      Takuya Hara on 2015-07-13.

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2015-07-17 14:34:02 -0700 (Fri, 17 Jul 2015) $
     $LastChangedRevision: 18173 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_slice2d_snap.pro $

(See projects/maven/swea/mvn_swe_slice2d_snap.pro)

## MVN_SWE_SPECPLOT

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

    PROCEDURE:   mvn_swe_specplot
    PURPOSE:
      Plots time series summary plots of SWEA SPEC data over arbitrarily long
      time spans.  The result is stored in a single TPLOT variable.

    USAGE:
      mvn_swe_specplot, trange=trange, orbit=orbit

    INPUTS:

    KEYWORDS:

           TRANGE:       Time range over which load data.  Must have at least two
                         elements, in any format accepted by time_double().  If
                         not specified, then load data using the current timespan.

           ORBIT:        Load data by orbit number (overrides TRANGE and TIMESPAN
                         methods).

           UNITS:        Units for plotting energy spectra.  Default = 'eflux'.

           ENERGY:       Energy for line plot.

           ERATIO:       Two energies for calculating a flux ratio.

           TAVG:         Time averaging when using ENERGY or ERATIO keywords.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-22 14:25:16 -0700 (Wed, 22 May 2024) $
     $LastChangedRevision: 32628 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_specplot.pro $

    CREATED BY:    David L. Mitchell  2015-05-06

(See projects/maven/swea/mvn_swe_specplot.pro)

## MVN_SWE_SPECSUM

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

    FUNCTION:   mvn_swe_specsum
    PURPOSE:
      Sums multiple SPEC data structures.  This is done by summing raw counts
      corrected by deadtime and then setting dtc to unity.

    USAGE:
      specsum = mvn_swe_specsum(spec)

    INPUTS:
           spec:           An array of SPEC structures to sum.

    KEYWORDS:

           QLEVEL:        Minimum quality level to sum (0-2, default=0):
                            2B = good
                            1B = uncertain
                            0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-07-04 13:35:32 -0700 (Thu, 04 Jul 2024) $
     $LastChangedRevision: 32721 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_specsum.pro $

    CREATED BY:    David L. Mitchell  03-29-14
    FILE: mvn_swe_specsum.pro

(See projects/maven/swea/mvn_swe_specsum.pro)

## MVN_SWE_SPICE_INIT

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

    PROCEDURE:   mvn_swe_spice_init
    PURPOSE:
      Initializes SPICE.

    USAGE:
      mvn_swe_spice_init

    INPUTS:

    KEYWORDS:

        TRANGE:        Time range for MAVEN spacecraft spk and ck kernels.  If not set,
                       then the current timespan is used.

        LIST:          After loading, list the kernels in use.

        FORCE:         If set, then clear all kernels and reload them based on TRANGE
                       or the current value of trange_full.  Otherwise, ask the user
                       for permission to clear and reload.

        SCLK_VER:      Force the SCLK kernel version to be this.  Sometimes needed for
                       accurate relative timing between MAG and SWEA.  If set, then
                       FORCE is also set.

        NOCK:          Do not load any CK kernels.  This allows ephemeris calculations
                       where the spacecraft orientation does not matter.  Useful for
                       calculations spanning long time intervals.

        BASEONLY:      Do not load any SPK or CK kernels.  The standard and frames
                       kernels are loaded to allow geometry calculations spanning long
                       time intervals.

        CSS:           Include the Comet Siding Spring SPK in the loadlist.

        STATUS:        Don't load anything; just give status.

        INFO:          Returns an array of structures providing detailed information
                       about each kernel, including coverage in time.

        VERBOSE:       Control level of messages.  (0 = suppress most messages)
                       Default is current value of swe_verbose.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-05-11 10:05:18 -0700 (Thu, 11 May 2023) $
     $LastChangedRevision: 31851 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_spice_init.pro $

    CREATED BY:    David L. Mitchell  09/18/13

(See projects/maven/swea/mvn_swe_spice_init.pro)

## MVN_SWE_STAT

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

    PROCEDURE:   mvn_swe_stat
    PURPOSE:
      Reports the status of SWEA data loaded into the common block.

    USAGE:
      mvn_swe_stat

    INPUTS:

    KEYWORDS:

        NPKT:          Returns the number of packets of each type.

        FULL:          If set, then display version information about IDL
                       and the SPICE and CDF dynamic load modules.

        SILENT:        Shhhh.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-03 11:57:08 -0700 (Tue, 03 Jun 2025) $
     $LastChangedRevision: 33362 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_stat.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/mvn_swe_stat.pro)

## MVN_SWE_STRUCT

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

    PROCEDURE:   mvn_swe_struct
    PURPOSE:
      Defines data structures for 3D, PAD, and ENGY products.  These work for both survey
      and archive.

      All times are for the center of the sample.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-03 11:54:58 -0700 (Tue, 03 Jun 2025) $
     $LastChangedRevision: 33361 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_struct.pro $

    CREATED BY:	David L. Mitchell  2013-07-26
    FILE:  mvn_swe_struct.pro

(See projects/maven/swea/mvn_swe_struct.pro)

## MVN_SWE_SUMPLOT

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

    PROCEDURE:   mvn_swe_sumplot
    PURPOSE:
      Plots information generated by MAVEN SWEA APID's.

      See 'mvn_swe_load_l0.pro' for details.

    USAGE:
      mvn_swe_sumplot

    INPUTS:

    KEYWORDS:

           EPH:          Load the MAVEN ephemeris and include a panel showing altitude,
                         color coded by nominal plasma regime.

           ORB:          Include the orbit number along the horizontal axis.

           SPICE:        Create a panel showing spice coverage.

           VNORM:        Subtract nominal values from all housekeeping voltages and plot all
                         voltage differences in a single panel.  Default = 1 (yes).

           CMDCNT:       Plot the SWEA command counter.

           SFLG:         Plot Energy Spectra and PAD's as spectrograms.  Default = 1 (yes).

           PAD_E:        PAD energy to plot.  Default = 280 eV.

           PAD_SMO:      Number of PAD energy bins to smooth over.

           A4_SUM:       Force sum mode for A4 and A5.  Not needed for EM or for FM post ATLO.

           EUNITS:       Units for plotting energy spectra (A4 and A5).  Default = 'crate'.

           TFIRST:       Earliest time to plot.  (Used for realtime plotting loop.)

           TITLE:        Title of TPLOT window.

           TSPAN:        Maximum number of hours to plot.  Default = plot all data.

           APID:         APID's to plot.  Housekeeping (APID 28) is always plotted.  3D
                         distributions (A0 and A1) are never plotted.  (Use swe_3d_snap to
                         display A0 and A1.)  This keyword controls plotting of A2-A5.
                         Default: ['A2','A4'].

           HSK:          String array indicating additional housekeeping panels to plot
                         (e.g., HSK = ['MCPHV'] during HV ramps).  Default = [''].

           FHSK:         Create tplot variables for fast housekeeping.  Default = 0 (no).

           FSHIFT:       Shift fast housekeeping packets to the start time of the first.

           FNORM:        Normalize the fast housekeeping channels to the nominal value.

           LUT:          Plot the active LUT.

           SIFCTL:       Plot SIF control register bits.

           TIMING:       Plot packet timing.  Useful to identify instrument mode and
                         dropped packets.  Default = 0 (no).

           LOADONLY:     Load tplot variables but do not plot.

           PNG:          Create a PNG image and place it in the default location.

           BURST:        Plot a color bar showing PAD burst coverage.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-01-03 14:09:26 -0800 (Fri, 03 Jan 2025) $
     $LastChangedRevision: 33043 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sumplot.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/mvn_swe_sumplot.pro)

## MVN_SWE_SUNDIR

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

    PROCEDURE:   mvn_swe_sundir
    PURPOSE:
      Calculates the direction of the Sun in SWEA coordinates.
      Optionally, calculates the direction of the Sun in additional
      frames specified by keyword.  The results are stored in TPLOT
      variables.

      Spacecraft frame:
        X --> APP boom axis
        Y --> +Y solar array axis
        Z --> HGA axis

      SWEA frame:
        X --> boundary between Anodes 15 and 0
        Y --> boundary between Anodes 3 and 4
        Z --> instrument symmetry axis
              (points "down" from top cap to pedestal)

      When boom is deployed, Z_sc = Z_swea

      If [X,Y,Z] is a unit vector, then
        phi   = atan(Y,X)
        theta = asin(Z)

      Some important angles:

        theta (deg)   : significance
      ---------------------------------------------------------------
        90 to 87      : entire sensor in shadow of pedestal
        < 87          : toroidal grids illuminated
        < 77          : upper deflector illuminated
        < 37          : top cap (periphery) illuminated
        17 to   0     : scalloped part of top cap illuminated
         0 to -10     : photons enter gap between hemispheres
      ---------------------------------------------------------------

      Negative values of theta are very unlikely in practice, since it
      means that the solar panels are facing away from the Sun.  The
      grids and upper deflector often become illuminated during comm
      passes and fly-Y.  The maximum angular separation between Earth
      and the Sun as seen from Mars is 47.5 deg.

      Toroidal grid support ribs are located every 45 degrees.  Each
      rib is 7-deg wide at theta = 0, with centers at:

        phi = 0, 45, 90, 135, 180, 225, 270, 315 degrees

    USAGE:
      mvn_swe_sundir, trange

    INPUTS:
           trange:   Time range for calculating the Sun direction.

    KEYWORDS:
           DT:       Time resolution (sec).  Default = 1, which is plenty
                     fast to resolve spacecraft rotations.

           PANS:     Named variable to hold the tplot variables created.

           FRAME:    Also calculate the Sun direction in one or more
                     frames specified by this keyword.  Default = 'MAVEN_SWEA'

           LIST:     List the key angles (as described above) and exit.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-03-01 14:50:37 -0800 (Wed, 01 Mar 2017) $
     $LastChangedRevision: 22886 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sundir.pro $

    CREATED BY:    David L. Mitchell  09/18/13

(See projects/maven/swea/mvn_swe_sundir.pro)

## MVN_SWE_SWEEP

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

    PROCEDURE:   mvn_swe_sweep
    PURPOSE:
      Generates a SWEA sweep table exactly as done in flight software (same digital
      commands, same checksum).  This table is combined with calibration data to
      determine energy sweep and deflection angle.  This routine can be used to
      generate new tables for upload to non-volatile memory in the PFDPU or to SWEA
      directly (via CDI).  It can also be used to create files for comparison with
      PFDPU EEPROM memory dumps.

      Nine pre-defined tables are provided via keyword TABNUM.  Tables 1-4 were only
      used in cruise and have been obsolete since orbit insertion.  Tables 5 and 6
      were loaded into flight software during commissioning in October 2014.  Table 5
      is used nearly all of the time.  Table 6 was used once a month until July 2018
      to calibrate and monitor the low energy response.  Tables 7-9 are high cadence
      tables at a single energy used during special observing sequences.

    KEYWORDS:
           RESULT:       Named variable to hold result structure: analyzer, deflector,
                         and V0 sweeps, energy/angle sweeps, energy resolution (dE/E)
                         and geometric factor vs. energy.

           TPLOT:        Create tplot variables, but do not plot them.

           DOPLOT:       Plot Va, Vd, V0, E, dE/E, X, TH, and GFW for one 2-sec sweep.
                         In a separate window, plot the deflection angle coverage as
                         a function of energy.  WARNING: this can alter the time range
                         of your tplot window.  Use keyword TSTART to align the sweep
                         variables with any other tplot variables.

           TSTART:       Arbitrary start time for DOPLOT.  Default = 0 ('1970-01-01').

           PROP:         Print the table properties: checksum, energy and angle ranges.

           TABNUM:       Table number corresponding to predefined settings.  Currently,
                         there are eight tables defined:

                           1 : Xmax = 6., Vrange = [0.75, 750.], V0scale = 1., /old_def
                               primary table for ATLO and Inner Cruise (first turnon)
                                 -64 < Elev < +66 ; 7 < E < 4650
                                  Chksum = 'CC'X

                           2 : Xmax = 6., Vrange = [0.75, 375.], V0scale = 1., /old_def
                               alternate table for ATLO and Inner Cruise (never used)
                                 -64 < Elev < +66 ; 7 < E < 2340
                                  Chksum = '1E'X

                           3 : Xmax = 5.5, Vrange = [3./Ka, 750.], V0scale = 0., /old_def
                               primary table for Outer Cruise
                                 -59 < Elev < +61 ; 3 < E < 4630
                                  Chksum = 'C0'X
                                  GSEOS svn rev 8360

                           4 : Xmax = 5.5, Vrange = [2./Ka, 750.], V0scale = 1., /old_def
                               alternate table for Outer Cruise
                                 -59 < Elev < +61 ; 3 < E < 4650
                                  Chksum = 'DE'X
                                  GSEOS svn rev 8361

                           5 : Xmax = 5.5, Vrange = [3./Ka, 750.], V0scale = 0.
                               primary table for Transition and Science
                                 -59 < Elev < +61 ; 3 < E < 4630
                                  Chksum = 'CC'X
                                  GSEOS svn rev 8481
                                  LUT = 0

                           6 : Xmax = 5.5, Vrange = [2./Ka, 750.], V0scale = 1.
                               alternate table for Transition and Science
                                 -59 < Elev < +61 ; 3 < E < 4650
                                  Chksum = '82'X
                                  GSEOS svn rev 8482
                                  LUT = 1

                           7 : Xmax = 5.5, Erange = [200.,200.], V0scale = 0.
                               Hires 32-Hz at 200 eV
                                 -59 < Elev < +61 ; E = 200
                                  Chksum = '00'X
                                  LUT = 2

                           8 : Xmax = 5.5, Erange = [50.,50.], V0scale = 0.
                               Hires 32-Hz at 50 eV
                                 -59 < Elev < +61 ; E = 50
                                  Chksum = '00'X
                                  LUT = 3

                           9 : Xmax = 5.5, Erange = [125.,125.], V0scale = 0.
                               Hires 32-Hz at 125 eV
                                 -59 < Elev < +61 ; E = 125
                                  Chksum = '00'X
                                  LUT = 1

                         Otherwise, use the following keywords to define the sweep.

           CHKSUM:       Use checksum to determine which table to use.  Currently,
                         this only uniquely identifies tables 5 and 6.  All high
                         cadence tables (7-9) have a checksum of zero.  The routine
                         mvn_swe_getlut can use one of three different methods for
                         determining the sweep table in use.

           Xmax:         Maximum ratio of deflector voltage to analyzer voltage.
                         (Controls maximum deflection angle.)  Default = 5.5

           V0scale:      Scale factor for V0 (a number from 0 to 1).
                             |V0| = E/2 < (25*V0scale) Volts
                         Default = 0.

           Vrange:       Voltage range of sweep (commanded).  Default = [0.75, 750.].

           Erange:       Energy range of sweep (commanded).  Takes precendence over Vrange.
                         This keyword allows one to set the energy range, correcting for
                         V0, if necessary.  No default.

           OLD_DEF:      Use the old method for sweeping the deflectors.  This is valid
                         for ground tests, early cruise checkout (Dec 6-7, 2013), and
                         outer cruise.

           DUMPFILE:     Saves an ascii hex dump to this named file, for comparison with
                         PFDPU EEPROM dump.

           CMDFILE:      Set this to the full path and filename for an ascii command file
                         for upload to the PFDPU.

           MEMADDR:      PFDPU memory address to begin loading table.  Only used if
                         FORMAT = 0 or 1.

           SWEBUF:       SWEA SLUT buffer to load table to (0-7).  Only used if FORMAT = 2.

           FORMAT:       Output sweep table in specified format:
                            0 = old PFDPU format (bytes)
                            1 = new PFDPU format (4-byte words)
                            2 = SWEA native format (2-byte words)

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-14 11:40:53 -0700 (Thu, 14 Jul 2022) $
     $LastChangedRevision: 30933 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_sweep.pro $

    CREATED BY:	David L. Mitchell  2014-01-03
    FILE:  mvn_swe_sweep.pro

(See projects/maven/swea/mvn_swe_sweep.pro)

## MVN_SWE_SWI_CAL

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

    PROCEDURE:   mvn_swe_swi_cal
    PURPOSE:
      Compares ion density from SWIA and electron density from SWEA for the purpose
      of cross calibration.  Beware of situations where SWEA and/or SWIA are not
      measuring important parts of the distribution.  Furthermore, SWEA data must be
      corrected for spacecraft potential (see mvn_scpot), and photoelectron
      contamination must be removed for any hope of a decent cross calibration.  For
      some distributions, secondary electrons can also bias the SWEA density estimate.

    USAGE:
      mvn_swe_swi_cal

    INPUTS:
       None.  Uses the current value of TRANGE_FULL to define the time range
       for analysis.  Calls timespan, if necessary, to set this value.

    KEYWORDS:
       COARSE:    Select SWIA 'coarse' data for analysis.  Provides density estimates
                  in the sheath.  Not recommended for cross calibration.

       FINE:      Select SWIA 'fine' data for analysis.  This is the default.

       ALPHA:     Calculate both proton and alpha densities using SWIA code.
                  Requires 'fine' data, so this forces FINE to be set.

       DDD:       Use SWEA 3D data for computing density.  Allows for bin
                  masking.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-01-08 16:07:28 -0800 (Mon, 08 Jan 2024) $
     $LastChangedRevision: 32342 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_swi_cal.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/swea/mvn_swe_swi_cal.pro)

## MVN_SWE_TABNUM

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

    FUNCTION:   mvn_swe_tabnum
    PURPOSE:
      Given a checksum, determines the corresponding table number.  Only returns
      table numbers >= 3.

      Eight tables are defined.  Tables 1-4 are obsolete.  Tables 5 and 6
      correspond to tables as loaded into flight software during commissioning
      in October 2014.  Table 8 will be loaded into flight software as part of
      an EEPROM update in late August 2018.  Table 7 will be loaded via CDI
      commands, since there is no contiguous block of PFDPU memory large enough
      to hold the table.

      Tables 7 and 8 both have a checksum of zero.  Use energy to resolve.

            1 : Xmax = 6., Vrange = [0.75, 750.], V0scale = 1., /old_def
                primary table for ATLO and Inner Cruise (first turnon)
                  -64 < Elev < +66 ; 7 < E < 4650
                   Chksum = 'CC'X

            2 : Xmax = 6., Vrange = [0.75, 375.], V0scale = 1., /old_def
                alternate table for ATLO and Inner Cruise (never used)
                  -64 < Elev < +66 ; 7 < E < 2340
                   Chksum = '1E'X

            3 : Xmax = 5.5, Vrange = [3./Ka, 750.], V0scale = 0., /old_def
                primary table for Outer Cruise
                  -59 < Elev < +61 ; 3 < E < 4630
                   Chksum = 'C0'X
                   GSEOS svn rev 8360

            4 : Xmax = 5.5, Vrange = [2./Ka, 750.], V0scale = 1., /old_def
                alternate table for Outer Cruise
                  -59 < Elev < +61 ; 3 < E < 4650
                   Chksum = 'DE'X
                   GSEOS svn rev 8361

            5 : Xmax = 5.5, Vrange = [3./Ka, 750.], V0scale = 0.
                primary table for Transition and Science
                  -59 < Elev < +61 ; 3 < E < 4630
                   Chksum = 'CC'X
                   GSEOS svn rev 8481
                loaded into SWEA LUT 0 (via FSW)

            6 : Xmax = 5.5, Vrange = [2./Ka, 750.], V0scale = 1.
                alternate table for Transition and Science
                  -59 < Elev < +61 ; 3 < E < 4650
                   Chksum = '82'X
                   GSEOS svn rev 8482
                loaded into SWEA LUT 1 (via FSW)

            7 : Xmax = 5.5, Erange = [200.,200.], V0scale = 0.
                Hires 32-Hz at 200 eV
                  -59 < Elev < +61 ; E = 200
                   Chksum = '00'X
                loaded into SWEA LUT 2 (via CDI)

            8 : Xmax = 5.5, Erange = [50.,50.], V0scale = 0.
                Hires 32-Hz at 50 eV
                  -59 < Elev < +61 ; E = 50
                   Chksum = '00'X
                loaded into SWEA LUT 3 (via FSW)

    USAGE:
      tabnum = mvn_swe_tabnum(i)

    INPUTS:
           i:            The checksum or table number.

    KEYWORDS:
           INVERSE:      Given a table number, return its checksum.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2019-03-15 12:38:10 -0700 (Fri, 15 Mar 2019) $
     $LastChangedRevision: 26808 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_tabnum.pro $

    CREATED BY:	David L. Mitchell  2014-01-03
    FILE:  mvn_swe_tabnum.pro

(See projects/maven/swea/mvn_swe_tabnum.pro)

## MVN_SWE_VALIDLUT

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

    FUNCTION:   mvn_swe_validlut
    PURPOSE:
      Checks for valid sweep lookup tables (LUTs).  The valid
      tables are: 3, 5 and 6.  Table 3 is primary during cruise,
      and was superceded by table 5 during transition on Oct. 6,
      2014.  Table 6 is very similar to 5, except that it enables
      V0.

      The high resolution tables (7 and 8) do not comform to the
      PDS archive specification and will need to be handled
      separately.

    USAGE:
      valid = mvn_swe_validlut(lut)

    INPUTS:
       lut:       Sweep table number.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2019-03-15 16:32:12 -0700 (Fri, 15 Mar 2019) $
     $LastChangedRevision: 26830 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_validlut.pro $

    CREATED BY:    David L. Mitchell  02-01-15
    FILE: mvn_swe_validlut.pro

(See projects/maven/swea/mvn_swe_validlut.pro)

## MVN_SWE_VERBOSE

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

    PROCEDURE:   mvn_swe_verbose
    PURPOSE:
      Sets the SWEA verbosity level.

    USAGE:
      mvn_swe_verbose, level

    INPUTS:

        level:         Verbosity level (0 = suppress most messages).

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-10-02 16:48:57 -0700 (Mon, 02 Oct 2017) $
     $LastChangedRevision: 24094 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/mvn_swe_verbose.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/swea/mvn_swe_verbose.pro)

## NIBBLE

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

    FUNCTION:   nibble
    PURPOSE:
      Converts a byte, integer, long, or long64 into an N-element
      byte array where the elements are the individual bits (0 or 1).
      LSB is stored in element 0, and MSB is stored in element N-1.

      Normally, one would decompose an unsigned integer into its bits,
      where each bit provides the on/off state of some flag or switch.
      However, it also works on signed integers, which introduces an
      ambiguity, for example:

        65533 = FF FD = 1 1 1 1 1 1 1 1 - 1 1 1 1 1 1 0 1
           -3 = FF FD = 1 1 1 1 1 1 1 1 - 1 1 1 1 1 1 0 1

      When using signed integers, the interpretation of the result is
      left to the user!

    USAGE:
      bits = nibble(i)

    INPUT:
           i  : A scalar of type byte, integer, long, or long64.
                Can be signed or unsigned.

    OUTPUT:
         bits : An N-element byte array, where N = 8, 16, 32, or 64,
                depending on the input data type.

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-08-11 09:09:54 -0700 (Fri, 11 Aug 2023) $
     $LastChangedRevision: 31985 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/nibble.pro $

    CREATED BY:	David L. Mitchell,  January 1998

(See projects/maven/swea/nibble.pro)

## NIBBLE_LONG

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

    FUNCTION:   nibble_long
    PURPOSE:
      Converts an unsigned long into a 32-element byte array where the
      elements are the individual bits (0 or 1).  LSB is stored in
      element 0 and MSB is in element 32.  No error checking for maximum
      speed.
    USAGE:
      bits = nibble_long(lword)
    INPUTS:
           lword : A unsigned long scalar.
    KEYWORDS:
    CREATED BY:	David L. Mitchell  02-06-11
    FILE:  nibble_long.pro
    VERSION:  1.0
    LAST MODIFICATION:  06-02-11

(See projects/maven/swea/nibble_long.pro)

## NIBBLE_WORD

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

    FUNCTION:   nibble_word
    PURPOSE:
      Converts an unsigned int into a 16-element byte array where the
      elements are the individual bits (0 or 1).  LSB is stored in
      element 0 and MSB is in element 15.  Note: if this function is
      fed a long, then it processes only the least significant word
      without crashing.  No error checking for maximum speed.
    USAGE:
      bits = nibble_word(word)
    INPUTS:
           word : A unsigned integer scalar.
    KEYWORDS:
    CREATED BY:	David L. Mitchell  01-15-98
    FILE:  nibble.pro
    VERSION:  1.2
    LAST MODIFICATION:  01-31-98

(See projects/maven/swea/nibble_word.pro)

## ROTATE_MAG_TO_SWE

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

    FUNCTION:   rotate_mag_to_swe
    PURPOSE:
      Rotates input vectors from MAG instrument coordinates to
      SWEA FSW coordinates.

    USAGE:
      v_out = rotate_mag_to_swe(v_in)

    INPUTS:
           v_in:     Input vectors with dimensions of N x 3.  The result
                     will have the same dimensions.

    KEYWORDS:

           MAGU:     Identifies the MAG sensor unit: 1 or 2.  Default is 1.
                     (MAG1 is used for on-board pitch angle mapping.)

           STOW:     Calculate the transformation for a stowed SWEA boom.
                     Default assumes a deployed boom.

           PAYLOAD:  Input vectors are in payload coordinates.

           INVERSE:  Reverse the rotation: swe to mag coordinates.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-10-31 14:15:03 -0700 (Fri, 31 Oct 2014) $
     $LastChangedRevision: 16106 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/rotate_mag_to_swe.pro $

    CREATED BY:    David L. Mitchell  09/18/13

(See projects/maven/swea/rotate_mag_to_swe.pro)

## SIGFIG

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

    FUNCTION:   sigfig
    PURPOSE:
      Simple function for rounding off.

    USAGE:
      y = sigfig(x,n)

    INPUTS:
           x:      The value to be rounded.  Can be an array.

           n:      Number of significant figures (>= 1).

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-03-31 18:06:44 -0700 (Mon, 31 Mar 2014) $
     $LastChangedRevision: 14725 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/sigfig.pro $

    CREATED BY:    David L. Mitchell  A Long Time Ago

(See projects/maven/swea/sigfig.pro)

## SWEICC

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

    PROCEDURE:   sweicc
    PURPOSE:
      Performs SWEA-SWIA cross calibration.  This is only intended for the
      SWEA team and is not designed for general use.

    USAGE:
      sweicc

    INPUTS:

    KEYWORDS:

           NBEEP:    Get the user's attention by beeping this many times.

           ODAT:     Spacecraft orbit database.  If not set, then it is
                     regenerated.

           CCRANGE:  Plotting limits for the cross calibration factor.

           NODEN:    Do not calculate ion or electron densities, which means
                     that the cross calibration is interrupted before it can
                     finish.  This interruption is needed to check and, if
                     necessary, refine the s/c potential.

           NOPAD:    Suppress the PAD panel to save time.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-06 16:33:10 -0700 (Mon, 06 May 2024) $
     $LastChangedRevision: 32558 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/sweicc.pro $

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

(See projects/maven/swea/sweicc.pro)

## SWEICCD

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

    PROCEDURE:   sweiccd
    PURPOSE:
      Performs SWEA-SWIA cross calibration.  This is the companion routine
      for sweicc.pro.  This is only intended for the SWEA team and is not
      designed for general use.

    USAGE:
      sweiccd

    INPUTS:

    KEYWORDS:

           NBEEP:    Get the user's attention by beeping this many times.

           ALPHA:    Calculate the ion density of H+ and He++ separately
                     using SWIA code.  Can result in better estimates of the
                     total ion number density.

           CCRANGE:  Plotting limits for the cross calibration factor.

           NOSWI:    Get ion density from the standard SWIA tplot variable
                     instead of calculating it from L2.  Not recommended.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-06 16:33:10 -0700 (Mon, 06 May 2024) $
     $LastChangedRevision: 32558 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/sweiccd.pro $

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

(See projects/maven/swea/sweiccd.pro)

## SWE_3D_SNAP

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

    PROCEDURE:   swe_3d_snap
    PURPOSE:
      Plots 3D snapshots in a separate window for times selected with the cursor in
      a tplot window.  Hold down the left mouse button and slide for a movie effect.
      This version uses plot3d and spec3d on packaged 3D data.

    USAGE:
      swe_3d_snap

    INPUTS:

    KEYWORDS:
           EBINS:         Energy bins to plot (passed to plot3d).  Default = 16 evenly
                          spaced bins.

           CENTER:        Longitude and latitude of the center [lon, lat].

           MAP:           Mapping projection, which is passed to plot3d_options.  See
                          the manual page for map_set for a list of projections:
                            aitoff (default)
                            cylindrical
                            lambert
                            mercator
                            mollweide
                            orthographic
                            ... etc.

           ZLOG:          If set, use a log color scale.

           ZRANGE:        Range for color bar.  [Does not work correctly.]

           SPEC:          Plot energy spectra for the 3D bins.
                            0 = Don't plot any spectra.  Default.
                            1 = All 96 spectra are overplotted in a single frame
                                with rainbow color scheme (blue: low bin numbers,
                                red: high bin numbers).
                            2 = Spectra are grouped and averaged using PGROUP and
                                then overplotted in a single frame with a rainbow
                                color scheme (as above).
                            3 = Spectra are grouped and averaged using PGROUP and
                                then plotted in an NxM grid of frames (one spectrum
                                per frame), where N is the number of phi bins (see
                                PGROUP), and M is the number of theta bins (always 6).
                                The spectrum for each frame is shown in green and the
                                average spectrum over all 3D bins is shown in red.
                                Note: The window for this plot should be as large as
                                possible to accommodate the many frames.  Best is to
                                devote and entire external monitor for this plot.
                                Once the snapshot window appears, you can move and
                                resize it as needed.  If you are using 'win', and
                                it's enabled, then 'win' will automatically make the
                                snapshot window as large it can while maintaining a
                                reasonable aspect ratio for each frame.

           PGROUP:        If SPEC > 1, then group the 3D bins in the phi (anode)
                          dimension to generate fewer spectra.  This keyword should
                          have one of five values: 1, 2, 4, 8, 16, where the number
                          indicates the number of adjacent anode bins to be grouped
                          and averaged together.  Default = 1 (no grouping).

           RESULT:        Returns the plot data from SPEC > 1, with the grouping set
                          by PGROUP.

           QRATIO:        If set, the Y axis for the SPEC plots becomes the ratio of
                          bad spectra (QUALITY=0) to good spectra (QUALITY=2) within
                          a selected time range with a linear Y axis.  Sets SUM = 1
                          to obtain a sufficient number of good and bad spectra, and
                          keyword QLEVEL is ignored.  Try to select time ranges
                          during which conditions are steady and the s/c potential
                          is constant.

           THICK:         Line thickness for the SPEC plots.  Default = 1.

           POT:           Plot the spacecraft potential on the SPEC plots.

           SCP:           Temporarily override any other estimates of the spacecraft
                          potential and force it to be this value.

           UNITS:         Data units for SPEC plots.  Default = 'crate'.

           ENERGY:        One or more energies to plot.  Overrides EBINS.

           ESUM:          Sum over the energies or channels specified by EBINS or
                          ENERGY.

           PADMAG:        If set, use the MAG angles in the PAD data to show the
                          magnetic field direction.

           DDD:           Named variable to hold a 3D structure at the last time
                          selected.  If this is a 3D structure, then plot a snapshot
                          of this instead of using the tplot window to select a time.

           SUM:           If set, use cursor to specify time ranges for averaging.

           TSMO:          Smoothing interval, in seconds.  Default is no smoothing.

           SMO:           Set smoothing in energy and angle.  Since there are only six
                          theta bins, smoothing in that dimension is not recommended.

                            smo = [n_energy, n_phi, n_theta]  ; default = [1,1,1]

                          This routine takes into account the 360-0 degree wrap when
                          smoothing, so there is no artificial seam.

           SYMDIR:        Calculate and overplot the symmetry direction of the
                          electron distribution.

           SYMENERGY:     Energy at which to calculate the symmetry direction.  Should
                          be > 100 eV.  Using the SMO keyword also helps.

           POWER:         Weighting function is proportional to eflux^power.  Higher
                          powers emphasize the peak of the distribution; lower powers
                          give more weight to surrounding cells.  Default = 2.

           SYMDIAG:       Plot symmetry weighting function in separate window.

           SUNDIR:        Plot the direction of the Sun in SWEA coordinates.

           LABEL:         If set, label the 3D angle bins.

           LABSIZE:       Character size for the labels.  Default = 1.

           WSCALE:        Window size scale factor.

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           ARCHIVE:       If set, show snapshots of archive data.

           BURST:         Synonym for ARCHIVE.

           MASK_SC:       Mask solid angle bins that are blocked by the spacecraft.

           PLOT_SC:       Draw an outline of the spacecraft as seen from SWEA on
                          the 3D plot.

           PLOT_FOV:      Replace the data with a "chess board" pattern to show the
                          field of view.  FOV masking, if any, will be shown.

           PADMAP:        Show the pitch angle map for the current spectrum.
                          Boundaries for the 3D solid angle bins are shown.  Bins
                          blocked by the spacecraft are marked with a yellow 'X'.

           TRANGE:        Plot snapshot for this time range.  Can be in any
                          format accepted by time_double.  (This disables the
                          interactive time range selection.)

           COLOR_TABLE:   Use this color table for plot3d.  Default is table 34
                          (rainbow).  This allows masked bins (black) to be
                          distinguished from bins with low signal (violet).

           REVERSE_COLOR_TABLE:  Reverse the color table (except for fixed colors).

           LINE_COLORS:   Set the line colors. (See line_colors.pro for more info.)

           QLEVEL:        Minimum quality level to plot (0-2, default=0):
                             2B = good
                             1B = uncertain
                             0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-18 14:04:25 -0700 (Fri, 18 Apr 2025) $
     $LastChangedRevision: 33268 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_3d_snap.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/swe_3d_snap.pro)

## SWE_3D_STITCH

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

    PROCEDURE:   swe_3d_stitch
    PURPOSE:
      Constructs 3D spectra from A0 and A1 packets.  Depending on the group parameter,
      1, 2, or 4 packets are needed to make one 3D.  The packets comprising one 3D
      should be generated very close in time; however, they are time tagged with
      millisec resolution, so there's a possibility that frames will have slightly
      different time tags.  This routine requires that they be created within 0.3 sec.

      The packets comprising a 3D must all be present, but they need not come in
      sequential order, as long as they are created within 0.3 seconds of each other.
      The PFDPU is known to occasionally write packets out of sequential order.

    USAGE:
      swe_3d_stitch

    INPUTS:

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-05-05 12:57:25 -0700 (Thu, 05 May 2022) $
     $LastChangedRevision: 30799 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_3d_stitch.pro $

    CREATED BY:    David L. Mitchell  07-24-12
    FILE: swe_3d_stitch.pro

(See projects/maven/swea/swe_3d_stitch.pro)

## SWE_3D_STRAHL_DIR

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

    PROCEDURE:
    	swe_3d_strahl_dir
    PURPOSE:
    	Determines the direction in SWEA coordinates of the strahl.
    AUTHOR:
    	David L. Mitchell
    CALLING SEQUENCE:
    	swe_3d_strahl_dir
    INPUTS:
    KEYWORDS:
           SMO:           Set smoothing in energy and angle.  Since there are only six
                          theta bins, smoothing in that dimension is not recommended.

                            smo = [n_energy, n_phi, n_theta]  ; default = [5,3,1]

           ENERGY:        Energy at which to calculate the symmetry direction.  Should
                          be > 100 eV.  Using the SMO keyword also helps.
                          Default = 130.

           POWER:         Weighting function is proportional to eflux^power.  Higher
                          powers emphasize the peak of the distribution; lower powers
                          give more weight to surrounding cells.  Default = 2.

           PANS:          Named variable to hold TPLOT variable names created.

           RESULT:        Named variable to hold the result.

           ARCHIVE:       Use archive data instead of survey data.

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2016-10-18 15:24:35 -0700 (Tue, 18 Oct 2016) $
     $LastChangedRevision: 22134 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_3d_strahl_dir.pro $

(See projects/maven/swea/swe_3d_strahl_dir.pro)

## SWE_3D_TIMING

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

    PROCEDURE:   swe_3d_timing
    PURPOSE:
      Disassembles A0 packets and sorts data in time sequence.

    USAGE:
      swe_3d_timing

    INPUTS:

    KEYWORDS:
           TRANGE:       Time range for processing, in any format
                         accepted by time_double().

           ANODE:        Anode number to process.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-10-31 14:15:03 -0700 (Fri, 31 Oct 2014) $
     $LastChangedRevision: 16106 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_3d_timing.pro $

    CREATED BY:    David L. Mitchell  06-25-13
    FILE: swe_3d_timing.pro

(See projects/maven/swea/swe_3d_timing.pro)

## SWE_A0_SNAP

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

    PROCEDURE:   swe_a0_snap
    PURPOSE:
      Plots 3D snapshots in a separate window for times selected with the cursor in
      a tplot window.  Hold down the left mouse button and slide for a movie effect.

      If housekeeping data exist (almost always the case), then they are displayed
      as text in a small separate window.

    USAGE:
      swe_3d_snap

    INPUTS:

    KEYWORDS:
           MODEL:         Plot a model of the 3D data product with the test pulser on in a
                          separate window.  (An analytic approximation to the test pulser
                          signal is used.  See 'swe_testpulser_model.pro' for details.)

           ZRANGE:        Sets color scale range.  Default = [1,3000].

           ZLOG:          Sets log color scaling.  Default = 1.

           WSCALE:        Scale factor for snapshot window sizes.

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           ARCHIVE:       If set, show snapshots of archive data (A1).

           BURST:         Synonym for ARCHIVE.

    CREATED BY:    David L. Mitchell  07-24-12
    FILE: swe_a0_snap.pro
    VERSION:   1.0
    LAST MODIFICATION:   07/24/12

(See projects/maven/swea/swe_a0_snap.pro)

## SWE_A2_SNAP

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

    PROCEDURE:   swe_a2_snap
    PURPOSE:
      Plots PAD snapshots in a separate window for times selected with the cursor in
      a tplot window.  Hold down the left mouse button and slide for a movie effect.

      If housekeeping data exist (almost always the case), then they are displayed
      as text in a small separate window.

    USAGE:
      swe_a2_snap

    INPUTS:

    KEYWORDS:
           MODEL:         Plot a model of the PAD data product with the test pulser on in
                          a separate window.  (An analytic approximation to the test pulser
                          signal is used.  See 'swe_testpulser_model.pro' for details.)

           DDD:           Calculate a pseudo-PAD data product from the nearest 3D spectrum,
                          and plot in a separate window.  Better when A0 and A2 have the same
                          energy grouping and time sampling.  Best when A0 and A2 are at max
                          rate with no energy grouping.  There is always the limitation that
                          3D spectra average adjacent anode bins at the highest upward and
                          downward deflections (80 solid angle bins instead of 96), whereas
                          PAD spectra do not.

           ENORM:         Normalize PAD at each energy step.

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           ZRANGE:        Sets color scale range.  Default = [1,3000].

           ZLOG:          Sets log color scaling.  Default = 1.

           ARCHIVE:       If set, show shapshots of archive data (A3).  Pseudo-PAD data is
                          calculated from 3D archive data (A1).

           BURST:         Synonym for ARCHIVE.

    CREATED BY:    David L. Mitchell  07-24-12
    FILE: swe_a2_snap.pro
    VERSION:   1.0
    LAST MODIFICATION:   07/24/12

(See projects/maven/swea/swe_a2_snap.pro)

## SWE_A4_SNAP

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

    PROCEDURE:   swe_a4_snap
    PURPOSE:
      Plots SPEC snapshots in a separate window for times selected with the cursor in
      a tplot window.  Hold down the left mouse button and slide for a movie effect.

      If housekeeping data exist (almost always the case), then they are displayed
      as text in a small separate window.

    USAGE:
      swe_a4_snap

    INPUTS:

    KEYWORDS:
           MODEL:         Plot a model of the SPEC data product with the test pulser on in
                          a separate window.  (An analytic approximation to the test pulser
                          signal is used.  See 'swe_testpulser_model.pro' for details.)

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           YRANGE:        Sets raw counts scale range.  Default = [1,3000].

           YLOG:          Sets log scaling.  Default = 1.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-19 14:52:42 -0700 (Thu, 19 Jun 2025) $
     $LastChangedRevision: 33396 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_a4_snap.pro $

    CREATED BY:    David L. Mitchell  07-24-12
    FILE: swe_a4_snap.pro

(See projects/maven/swea/swe_a4_snap.pro)

## SWE_CAL_SNAP

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

    PROCEDURE:   swe_cal_snap
    PURPOSE:
      Plots snapshots of calibration data in a separate window for times selected
      with the cursor in a tplot window.  Hold down the left mouse button and slide
      for a movie effect.

      Calibration data can be extracted from 3D, PAD, or SPEC data.

    USAGE:
      swe_cal_snap

    INPUTS:

    KEYWORDS:
           DDD:           Get calibration from 3D data.

           PAD:           Get calibration from PAD data.

           SPEC:          Get calibration from SPEC data.

           UNITS:         Data units.

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           ARCHIVE:       If set, show snapshots of archive data.

           BURST:         Synonym for ARCHIVE.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-14 11:40:53 -0700 (Thu, 14 Jul 2022) $
     $LastChangedRevision: 30933 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_cal_snap.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/swe_cal_snap.pro)

## SWE_DEADTIME

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

    FUNCTION:   swe_deadtime
    PURPOSE:
      Calculates the deadtime correction given the measured count rate and the
      deadtime.  The correction is the ratio of the measured count rate to the
      true count rate.  Works for both non-paralyzing and paralyzing
      behavior.

      For non-paralyzing deadtime: R' = R / (1 + R*tau), where R' is the
      measured count rate, R is the true count rate, and tau is the deadtime.
      The measured count rate asympotically approaches 1/tau.  This is the
      default.

      For paralyzing deadtime: R' = R * exp(-R*tau).  The measured count rate
      peaks at 1/tau and drops rapidly at higher true count rates.  It is two
      valued, so one must assume which side of the peak when estimating the
      true count rate from the measured count rate.  This routine assumes that
      R' <= 1/tau.  For a given deadtime, a paralyzing system is more aggressive
      because more events are missed.

    USAGE:
      dtc = swe_deadtime(rate)

    INPUT:
           rate:         An array of measured raw count rates.

    OUTPUT:
           dtc:          Deadtime correction factor, or the ratio of the
                         measured count rate to the true count rate.

    KEYWORDS:
           DEADTIME:     Deadtime.  Default is obtained from mvn_swe_calib.
                         Once set, this value is persistent.

           PARALYZE:     If set, use paralyzing deadtime.  Once set, this
                         value is persistent.

           INIT:         If set, initialize the paralyzable deadtime function.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-12-15 13:01:44 -0800 (Tue, 15 Dec 2020) $
     $LastChangedRevision: 29491 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_deadtime.pro $

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

(See projects/maven/swea/swe_deadtime.pro)

## SWE_ENGY_SNAP

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

    PROCEDURE:   swe_engy_snap
    PURPOSE:
      Plots omnidirectional energy spectrum snapshots in a separate window for times
      selected with the cursor in a tplot window.  Hold down the left mouse button
      and slide for a movie effect.

    USAGE:
      swe_engy_snap

    INPUTS:

    KEYWORDS:
           UNITS:         Plot the data in these units.  See mvn_swe_convert_units.
                          Default = 'eflux'.

           TIMES:         Make a plot for these times.  (Placeholder only.)

           TPLOT:         Get energy spectra from tplot variable instead of SWEA
                          common block.

           FIXY:          Use a fixed y-axis range.  Default = 1 (yes).

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           ARCHIVE:       If set, show shapshots of archive data (A5).

           BURST:         Synonym for ARCHIVE.

           SPEC:          Named variable to hold the energy spectrum at the last time
                          selected.

           RESULT:        Named variable to hold the data used in the various plots.

           SUM:           If set, use cursor to specify time ranges for averaging.

           TSMO:          Smoothing interval, in seconds.  Default is no smoothing.

           ERROR_BARS:    If set, plot energy spectra with error bars.  Does not work
                          when the TPLOT option (see above) is set, because statistical
                          uncertainties are not stored in the tplot variable.

           POT:           Overplot an estimate of the spacecraft potential.  Must run
                          mvn_scpot first.

           SCP:           Temporarily override any other estimates of the spacecraft
                          potential and force it to be this value.

           SHIFTPOT:      Correct for the spacecraft potential.  If the data are in
                          instrument units (COUNTS, RATE, CRATE), then the energy
                          scale is shifted by the amount of the potential, but the
                          signal level remains unchanged.  If the data are in physical
                          units (FLUX, EFLUX, DF), then the signal level is also
                          adjusted to ensure conservation of phase space density.

           DEMAX:         Maximum width of spacecraft potential signature.

           PEPEAKS:       Overplot the nominal energies of the photoelectron energy peaks
                          at 23 and 27 eV.

           CUII:          Overplot ionization potential of Cu (hemispheres and top cap are
                          coated with Cu2S).  This is the threshold for electron impact
                          ionization and secondary electron contamination inside the
                          instrument.

           PEREF:         Overplot photoelectron reference spectra

           BCK:           Plot background level (Potassium-40 decay and penetrating
                          particles only).

           MAGDIR:        Print magnetic field geometry (azim, elev, clock) on the plot.

           PDIAG:         Plot potential estimator in a separate window.

           PXLIM:         X limits (Volts) for diagnostic plot.

           PYLIM:         Y limits (Volts) for diagnostic plot.

           MB:            Perform a Maxwell-Boltzmann fit to determine density and
                          temperature.  Uses a moment calculation to determine the
                          halo density, which is defined as the high energy residual
                          after subtracting the best-fit Maxwell-Boltzmann.

           KAP:           Instead of the halo moment calculation, fit the halo with
                          a kappa function to estimate halo density.

           MOM:           Instead of fitting the core with a Maxwell-Boltzmann, use
                          a moment calculation for all energies above the spacecraft
                          potential.

           ERANGE:        Energy range for computing the moment.  Only effective when
                          keyword MOM is set.

           FLEV:          Calculate the signal level at this energy, using interpolation
                          as needed.

           SCAT:          Plot the scattered photoelectron population, which is defined
                          as the low-energy residual after subtracting the best-fit
                          Maxwell-Boltzmann.

           SEC:           Calculate secondary electron spectrum using one of two methods:
                            SEC = 1 --> Andreone
                            SEC = 2 --> Evans

           SCONFIG:       Structure of parameters for the secondary electron models.

                            {e0:e0, s0:s0, e1:e1, s1:s1, scl:scl}

           NORAW:         If SEC is set, do not plot the uncorrected or secondary spectra;
                          just plot the corrected spectrum.

           DDD:           Create an energy spectrum from the nearest 3D spectrum and
                          plot for comparison.

           ABINS:         Anode bin mask (16 elements: 0=off, 1=on).  Default = all on.

           DBINS:         Deflector bin mask (6 elements: 0=off, 1=on).  Default = all on.

           OBINS:         3D solid angle bin mask (96 elements: 0=off, 1=on).
                          Default = reform(ABINS # DBINS).

           MASK_SC:       Mask solid angle bins that view the spacecraft.  Default = yes.
                          This masking is in addition to OBINS.

           NOERASE:       Overplot all spectra after the first.

           VOFFSET:       Vertical offset when overplotting spectra.

           RAINBOW:       With NOERASE, overplot spectra using up to 6 different colors.

           RCOLORS:       Instead of the default rainbow colors, use these instead.
                          Any number of colors is allowed.  The routine cycles through
                          the colors as needed, if there are many spectra to plot.

           POPEN:         Set this to the name of a postscript file for output.

           WSCALE:        Window size scale factor.

           CSCALE:        Character size scale factor.

           XRANGE:        Override the default horizontal axis range with this.

           YRANGE:        Override the default vertical axis range with this.

           TRANGE:        Plot snapshot for this time range.  Can be in any
                          format accepted by time_double.  (This disables the
                          interactive time range selection.)

           TWOT:          Compare energy of peak energy flux and temperature of
                          Maxwell-Boltzmann fit. (Nominally, E_peak = 2*T)

           SHOWDEAD:      Show the scaled deadtime correction.  Does not work with
                          summed spectra (keywords SUM and TSMO) because spectra
                          are summed in units of corrected count rate (CRATE) so
                          that the deadtime corrections for the individual spectra
                          are lost.

           DEAD:          Same as SHOWDEAD.

           BACKGROUND:    Show the background on the plot.

           COLOR_TABLE:   Use this color table for all plots.

           REVERSE_COLOR_TABLE:  Reverse the color table (except for fixed colors).

           LINE_COLORS:   Use this for the line colors.

           QLEVEL:        Minimum quality level for summing and plotting.  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.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 09:23:37 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33402 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_engy_snap.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/swe_engy_snap.pro)

## SWE_ENGY_TIMING

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

    PROCEDURE:   swe_engy_timing
    PURPOSE:
      Disassembles A4 packets and sorts data in time sequence.

    USAGE:
      swe_engy_timing

    INPUTS:

    KEYWORDS:
           CAL:           Use calibrated data (mvn_swe_engy).

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-23 15:48:33 -0700 (Fri, 23 May 2025) $
     $LastChangedRevision: 33331 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_engy_timing.pro $

    CREATED BY:    David L. Mitchell  06-25-13
    FILE: swe_engy_timing.pro

(See projects/maven/swea/swe_engy_timing.pro)

## SWE_GETMAG_QL

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

    PROCEDURE:   swe_getmag_ql
    PURPOSE:
      Loads MAG data from one of two sources:

          (1) MAG quicklook sts files provided by the MAG team.  These are converted
              into IDL save files -- this routine restores the save files.  These
              data include corrections for nominal offsets.  MAG1 data only.  Typically
              available one day after the L0 data arrive.

          (2) Davin's decommutator.  These are loaded directly from the L0 data.
              These data do not have offset corrections.  Both MAG1 and MAG2 data are
              provided.

      Once loaded, the data are smoothed to the 2-sec SWEA resolution.

      OBSOLETE: Use mvn_swe_addmag instead.

    USAGE:
      swe_getmag_ql

    INPUTS:
           trange:        Time range for loading data.

    KEYWORDS:
           FILENAME:      Full path and file name containing L0 MAG data.
                          Can be an array of file names.  Loading MAG data
                          from multiple files can take a long time.

           TOFF:          Time offset for MAG data.  This accounts for any
                          differences in MAG vs. SWEA timing.  Ideally, this
                          should be zero, once both decommutators are correct.
                          Use fit_pad_mag to empirically determine the offset.

           STS:           Read in MAG STS files generated by the MAG team.
                          Default is to use Davin's decommutator.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-12-11 16:20:52 -0800 (Thu, 11 Dec 2014) $
     $LastChangedRevision: 16465 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_getmag_ql.pro $

    CREATED BY:    David L. Mitchell  03/18/14

(See projects/maven/swea/swe_getmag_ql.pro)

## SWE_HSK_SNAP

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

    PROCEDURE:   swe_hsk_snap
    PURPOSE:
      Plots housekeeping snapshots for times selected with the cursor in a tplot
      window.

    USAGE:
      swe_hsk_snap, hsk=hsk

    INPUTS:

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-14 11:40:53 -0700 (Thu, 14 Jul 2022) $
     $LastChangedRevision: 30933 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_hsk_snap.pro $

    CREATED BY:    David L. Mitchell  07-25-12

(See projects/maven/swea/swe_hsk_snap.pro)

## SWE_LOWE_CLUSTER

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

    PROCEDURE:   swe_lowe_cluster
    PURPOSE:
      Sporadic low-energy anomaly cluster analysis.

    USAGE:
      swe_lowe_cluster [, KEYWORD=value, ...]

    INPUTS:

    KEYWORDS:
           TRANGE:   Process data over this time range.

           WIDTH:    Boxcar width in points for performing cluster analysis.
                     Odd number.  Default = 75.

           NPTS:     Half-width of boxcar for calculating upper envelope.
                     Default = 16.

           LAMBDA:   Smoothing parameter for spline_smooth.  Default = 1.

           FRAC:     Fraction of lowest points to ignore in calculating smooth
                     curve through upper envelope of data.  Default = 0 (use
                     all points).

           OUTLIER:  With one-cluster analysis, this discard outliers more than
                     this many standard deviations from the mean.

           MINPTS:   If OUTLIER is set, this specifies the minimum number of
                     points remaining after discarding outliers.  If too many
                     points are flagged as outliers, then cluster analysis is
                     preferred.  Default = WIDTH - 5.

           TSTOP:    Times of shadow boundaries.

           BUFFER:   Buffer zone at shadow boundaries.  All quality flags within
                     BUFFER seconds of the boundary are set to unity.  The buffer
                     zone is asymmetric about the shadow boundary because the flux
                     changes more gradually on the dark side of the boundary.
                     Default [sun,dark] = [8,16] seconds.

           MINDELTA: Minimum cluster separation for identifying anomalous spectra.
                     Default = 1 (sigma).

           MAXRATIO: Maximum variance ratio for identifying anomalous spectra.
                     Default = 0.4 (minvar/maxvar).

           MAXBAD:   The maximum fraction of points within a boxcar to flag as bad.
                     Default = 0.7.

           MOBETAH:  For the low energy band, the cluster with more points is taken
                     to be "good".  Not recommended.

           MINSUP:   Minimum density suppression. The low-energy anomaly usually
                     results in a suppression of 0.4-0.8 for both the low and high
                     energy bands.  Larger apparent suppression factors can be caused
                     by attempting to use cluster analysis on large real density
                     changes, such as during discrete precipitation events in shadow.
                     This keyword sets the quality flag to 1 (unknown) whenever the
                     suppression falls below MINSUP.  Default = 0.3

           FLAG:     Quality flag: (2 = good, 1 = unknown, 0 = bad).

           QUALITY:  Structure containing the time and flag.

           DIAG:     Returns structure of diagnostic information.

           TPLOT:    Make tplot panels of diagnostics.

           SETFLAG:  Set the quality flag in the SPEC, PAD, and 3D data structures.

           QUIET:    Shhh.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-05-01 09:13:11 -0700 (Wed, 01 May 2024) $
     $LastChangedRevision: 32542 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_lowe_cluster.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/swea/swe_lowe_cluster.pro)

## SWE_MAKE_HIRES

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

    PROCEDURE:   swe_make_hires
    PURPOSE:
      Loads L0 data containing hires SWEA data (LUT = 7,8,9) and 32-Hz MAG data,
      creates hires PAD and SPEC data, and makes tplot variables with merged hires
      and normal resolution data.  SWEA and tplot save files are created.

    USAGE:
      swe_make_hires, date

    INPUTS:
           date:      Date to process, in any format accepted by time_double().
                      Only the date (YYYY-MM-DD) is used; HH:MM:SS are ignored.

    KEYWORDS:
           TPLOT:     If set, create a time series plot of the data.

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

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

(See projects/maven/swea/swe_make_hires.pro)

## SWE_MAXBOL

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

    PROCEDURE:   swe_maxbol
    PURPOSE:
      Maxwell-Boltzmann distribution for fitting SWEA electron energy spectra.
      The reference frame is at the instrument aperture, after the electrons
      have been accelerated by the spacecraft potential.

      Correction for spacecraft potential, but no correction for bulk flow.

      Units are energy flux [eV/cm2-sec-ster-eV].

    USAGE:
        eflux = swe_maxbol(E, par=p)

    INPUTS:

        E:             Measured energy [eV].

    KEYWORDS:

        PARAM:         Parameter structure.

                       p = {n    :    1.0d  , $   ; core density [cm-3]
                            T    :   10.0d  , $   ; core temperature [eV]
                            k_n  :    0.0d  , $   ; halo density [cm-3]
                            k_vh : 4000.0d  , $
                            k_k  :    5.0d  , $
                            pot  :    0.0d     }  ; spacecraft potential [V]

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-09-22 09:25:06 -0700 (Mon, 22 Sep 2014) $
     $LastChangedRevision: 15831 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_maxbol.pro $

    CREATED BY:    David L. Mitchell  03-29-13
    FILE: swe_maxbol.pro

(See projects/maven/swea/swe_maxbol.pro)

## SWE_N_3D

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

    FUNCTION:	swe_n_3d(dat,EBINS=ebins,ABINS=abins,DBINS=dbins)
    INPUT:
    	dat:	structure,	2d data structure filled mvn_swe_get3d
    KEYWORDS
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include, na = dat.nenergy
    	ABINS:	bytarr(16),	optional, anode bins array for integration
    					0,1=exclude,include
    	DBINS:	bytarr(6),	optional, deflector bins array for integration
    					0,1=exclude,include

       OBINS:  bytarr(96), optional, solid angle bins for integration
                       0,1=exclude,include
    PURPOSE:
    	Returns the density, n, 1/cm^3

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden	added more keywords
       14-7-6      D.Mitchell  redefined keywords,
                               added correction for spacecraft potential

(See projects/maven/swea/swe_n_3d.pro)

## SWE_PAD32HZ_UNPACK

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

    FUNCTION:   swe_pad32hz_unpack
    PURPOSE:
      Expands a high time resolution PAD structure into 64 single-energy
      PAD structures, with appropriate timing, magnetic field data, and
      pitch angle mapping.

    USAGE:
      pad32hz = swe_pad32hz_unpack(pad)

    INPUTS:
           pad:          Array of 64-energy PAD structures with sweep
                         tables > 6.  (Tables <= 6 are ignored.)

    OUTPUT:
           pad32Hz:      Array of single-energy PAD structures with
                         high time resolution.

    KEYWORDS:
           none

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-03 11:53:01 -0700 (Tue, 03 Jun 2025) $
     $LastChangedRevision: 33360 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_pad32hz_unpack.pro $

    CREATED BY:	David L. Mitchell  2019-03-01

(See projects/maven/swea/swe_pad32hz_unpack.pro)

## SWE_PAD_SNAP

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

    PROCEDURE:   swe_pad_snap
    PURPOSE:
      Plots PAD snapshots in a separate window for times selected with the cursor in
      a tplot window.  Hold down the left mouse button and slide for a movie effect.
      A PAD snapshot is an pitch angle X energy spectrogram at the selected time.
      Optionally, keyword ENERGY can be used to plot a PAD in histogram mode for a
      single energy.

    USAGE:
      swe_pad_snap

    INPUTS:

    KEYWORDS:
           ENERGY:        Energy (eV) to use for the histogram plot.

           UNITS:         Plot PAD data in these units.

           LASTPAD:       Named variable to hold a PAD structure at the last time
                          selected.

           RESULT:        Named variable to hold the data used in the various plots.

           DDD:           If set, compare with the nearest 3D spectrum.

           CENTER:        Specify the center azimuth for 3D plots.  Only works when DDD
                          is set.

           SUM:           If set, use cursor to specify time ranges for averaging.

           TSMO:          Smoothing interval, in seconds.  Default is no smoothing.

           SMO:           Number of energy bins to smooth over.

           NORM:          At each energy step, normalize the distribution to the mean.

           POT:           Overplot an estimate of the spacecraft potential.  Must run
                          mvn_scpot first.  Default = 1 (yes).

           SCP:           Temporarily override any other estimates of the spacecraft
                          potential and force it to be this value.

           SHIFTPOT:      Correct for the spacecraft potential.  If the data are in
                          instrument units (COUNTS, RATE, CRATE), then the energy
                          scale is shifted by the amount of the potential, but the
                          signal level remains unchanged.  If the data are in physical
                          units (FLUX, EFLUX, DF), then the signal level is also
                          adjusted to ensure conservation of phase space density.

           SEC:           Remove secondary electrons.

           SCONFIG:       Structure of parameters for the secondary electron models.

                            {e0:e0, s0:s0, e1:e1, s1:s1, scl:scl}

           LABEL:         Label the anode and deflection bin numbers (label=1) or the
                          solid angle bin numbers (label=2).

           KEEPWINS:      If set, then don't close the snapshot window(s) on exit.

           KILLWINS:      If set, then close the snapshot window(s) on exit no matter what.
                          Takes precedence over KEEPWINS.

           MONITOR:       Put snapshot windows in this monitor.  Monitors are numbered
                          from 0 to N-1, where N is the number of monitors recognized
                          by the operating system.  See win.pro for details.

           ARCHIVE:       If set, show snapshots of archive data.

           BURST:         Synonym for ARCHIVE.

           DIR:           If set, show some useful information with
                          respect to the observed vector magnetic field
                          in the MSO and LGEO(local geographic coordinate).

           ABINS:         Anode bin mask -> 16 elements (0 = off, 1 = on)
                          Default = replicate(1,16)

           DBINS:         Deflector bin mask -> 6 elements (0 = off, 1 = on)
                          Default = replicate(1,6)

           OBINS:         3D solid angle bin mask -> 96 elements (0 = off, 1 = on)
                          Default = reform(ABINS # DBINS)

           MASK_SC:       Mask the spacecraft blockage.  This is in addition to any
                          masking defined by the ABINS, DBINS, and OBINS.
                          Default = 1 (yes).  Set this to 0 to disable and use the
                          above 3 keywords only.

           SPEC:          Plot energy spectra for parallel, anti-parallel, and
                          90-degree pitch angle populations.  The value of this
                          keyword is the pitch angle width (deg) that is used
                          to separate the populations:

                            parallel      : 0 to SPEC degrees
                            middle        : SPEC to (180 - SPEC) degrees
                            anti-parallel : (180 - SPEC) to 180 degrees

                          Pitch angle bins must be entirely contained within
                          one of these ranges to be included.

                          Any value of SPEC < 30 deg is taken to be 30 deg.

            NOMID:        When using keyword SPEC, do not plot the energy spectrum
                          for the middle range of pitch angles.  Plot only the
                          spectra for parallel and anti-parallel populations.

            PLOTLIMS:     Plot dashed lines at the limits of the pitch angle
                          coverage.

            PEP:          Plot vertical dashed lines at the nominal photoelectron
                          energy peaks at 23 and 27 eV (due to ionization of CO2
                          and O by 304-Angstrom He-II line).

            RESAMPLE:     Two independent pitch angle distributions are measured
                          for each PAD data structure.  This keyword averages them
                          together and plots the result.

            UNCERTAINTY:  If set, show the relative uncertainty of the resampled PAD.

            ERROR_BARS:   Plot energy spectra with error bars.  Default = 1 (yes).

            MINCOUNTS:    Minumum number of counts for plotting.  Default = 10.

            MAXRERR:      Maximum relative error in resampled PADs.  Default = 10
                          (i.e., disabled).  Set this to some lower value (~1) to
                          filter out data with large relative errors.

            HIRES:        Use 32-Hz MAG data to map pitch angle with high time
                          resolution within a 2-second SWEA measurement cycle.  A
                          separate pitch angle map is determined for each of the
                          64 energy steps.  You must first load 32-Hz MAG data for
                          this keyword to be effective.  Please read warnings in
                          mvn_swe_padmap_32Hz.pro.

            FBDATA:       Tplot variable name that contains the 32-Hz MAG data.
                          Default = 'mvn_B_full'.

            ADIABATIC:    Calculate and display the adiabatic condition:

                            (1/B)*(dB/dx)*Rg << 1

                          which is the fractional change in the magnetic field over
                          one gyroradius.  Only works when HIRES is set.

            POPEN:        Set this to the name of a postscript file for output.

            INDSPEC:      To plot out the energy spectrum for each PA bins

            TWOPOT:       Set to a two-element array to allow shifting different
                          potentials on parallel and anti-parallel directions.
                            -> Assumes data are in EFLUX units.
                            -> Assumes SHIFTPOT is not set.

            VDIS:         Plot the velocity distribution function based on the PAD
                          data.  This will be symmetric because each PAD is a 2D
                          cut through the 3D distribution.

            XRANGE:       Override Espec energy range with this.

            YRANGE:       Override Espec flux range with this.

            ZRANGE:       Override default color scale range with this.

            TRANGE:       Plot snapshot for this time range.  Can be in any
                          format accepted by time_double.  (This disables the
                          interactive time range selection.)

            PYRANGE:      Override normalized PAD y plot range with this.

            WSCALE:       Scale all window sizes by this factor.  Default = 1.

            CSCALE:       Scale all characters by this factor.  Default = 1.

            PADMAP:       Show the pitch angle map for the current spectrum.
                          Boundaries for the 3D solid angle bins are shown, and
                          if TSMO=0 and SUM=0, then boundaries for the PAD cut
                          are also shown.  Bins blocked by the spacecraft are
                          marked with a yellow 'X'.

            COLOR_TABLE:  Use this color table for all plots.

            REVERSE_COLOR_TABLE:  Reverse the color table (except for fixed colors).

            LINE_COLORS:  Use this for the line colors.

            NOTE:         Insert a text label.  Keep it short.

            QLEVEL:       Minimum quality level to plot (0-2, default=0):
                             2B = good
                             1B = uncertain
                             0B = affected by low-energy anomaly

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-05 14:36:55 -0700 (Sat, 05 Apr 2025) $
     $LastChangedRevision: 33233 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_pad_snap.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/swe_pad_snap.pro)

## SWE_PAD_TIMING

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

    PROCEDURE:   swe_pad_timing
    PURPOSE:
      Disassembles A2 packets and sorts data in time sequence.

    USAGE:
      swe_pad_timing

    INPUTS:

    KEYWORDS:
           TRANGE:       Time range for processing, in any format
                         accepted by time_double().

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-10-31 14:15:03 -0700 (Fri, 31 Oct 2014) $
     $LastChangedRevision: 16106 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_pad_timing.pro $

    CREATED BY:    David L. Mitchell  06-25-13
    FILE: swe_pad_timing.pro

(See projects/maven/swea/swe_pad_timing.pro)

## SWE_PLOT_FHSK

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

    PROCEDURE:   swe_plot_fhsk
    PURPOSE:
      Makes tplot variables for SWEA fast housekeeping data (A6).

    USAGE:
      swe_plot_fhsk

    INPUTS:
           None:  All information is obtained from the common block.

    KEYWORDS:
           PANS:          Returns the tplot variables created.

           TSPAN:         Include only fast housekeeping packets within this
                          time span.  This is different from the next keyword!

           TRANGE:        Returns a 2xN array of time ranges for the N
                          tplot variables created.  This makes it easy to
                          zoom in to view each channel.  For example:

                            tplot, pans[i], trange=trange[*,i]

           TSHIFT:        If set, then for each housekeeping channel, shift
                          data from multiple sweeps to start at the time
                          of the first sweep.  This makes it easy to compare
                          multiple channels synchronized to the sweep.  In
                          this case, TRANGE will have just two elements.

           VNORM:         If set, normalize voltage housekeeping data to the
                          nominal value for each channel.  Temperatures and
                          sweep voltages that do not have a nominal value are
                          left unchanged.

           AVG:           If set, average multiple sweeps for each channel.
                          Automatically sets TSHIFT.

           MODEL:         When any of the fast housekeeping channels are one
                          of the analyzer voltages (ANALV, DEF1V, DEF2V, V0V),
                          overlay the expected voltage.

           TABLE:         Use this sweep table instead of the one obtained from
                          housekeeping.  This can help when the timing of fast
                          housekeeping packets (when they are put into telemetry)
                          does not line up with science packets.
                          See mvn_swe_getlut for details.

           RESULT:        Named variable to hold structure of results.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-10-13 09:34:06 -0700 (Thu, 13 Oct 2022) $
     $LastChangedRevision: 31169 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_plot_fhsk.pro $

    CREATED BY:    David L. Mitchell  2017-01-15

(See projects/maven/swea/swe_plot_fhsk.pro)

## SWE_ROTATE

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

    PROCEDURE:   swe_rotate
    PURPOSE:
      Rotates SWEA 3D or PAD look directions into any valid SPICE frame.

    USAGE:
      swe_rotate, dat, frame=frame, result=result

    INPUTS:
           dat:          A single or an array of SWEA 3D or PAD structures.
                         See mvn_swe_get3d() and mvn_swe_getpad().

    KEYWORDS:
           FRAME:        SPICE frame to rotate the look directions into.  Required.
                         No default.  This must be a valid SPICE frame, although
                         you can use minimum matching fragments (see mvn_frame_name).

           RESULT:       A 3 x N x M array of vectors in the requested frame, where
                         the first dimension is the 3 cartesian components (x,y,z),
                         the second dimension is the number of times (N), and
                         the third dimension is the number of look directions (M).
                         Since this is a pure rotation, all vectors have unit length.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-10-21 13:08:06 -0700 (Wed, 21 Oct 2020) $
     $LastChangedRevision: 29265 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_rotate.pro $

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

(See projects/maven/swea/swe_rotate.pro)

## SWE_SHAPE_PAR_PAD_L2_3PA

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

    PROCEDURE:
       swe_shape_par_pad_l2_3pa

    PURPOSE:

       Calculate pitch angle resolved shape parameters for loaded SWEA L2
       PAD survey data for three PA ranges and create tplot variable "Shape_PAD"

    AUTHOR:
       Shaosui Xu

    CALLING SEQUENCE:

       If desire to correct for spacecraft potential, first run "mvn_swe_sc_pot"

    INPUTS:

       none

    KEYWORDS:

       BURST:    If set to 1, then use burst data to calculate the shape parameter,
                 however, not tested yet

       SPEC:     A pitch angle in degrees given to average.
                 PA [0,SPEC] & [(180-SPEC),180] for two directions.
                 The default value is 30

       ERANGE:  Shape parameter calculated based on the spectrum within this energy
                range. The default values are [20,80] eV

       MIN_PAD_EFLUX: Minimum energy flux level.

       MAG_GEO: A MAG structure that contains magnetic elevation angle. If not given,
                The program will load MAG data in GEO coordinates.

       POT:     If set to 1, this program will correct the spacecraft potential for
                the electron energy spectrum.

       NSMO:    Number of spectra to average over before calculating shape parameter.
                Default = 1 (no smoothing).

       TSMO:    Boxcar smooth the PADs with this width (in seconds) before calculating
                the shape parameter.  This method is slower but handles data gaps and
                changes in instrument mode.  Takes precedence over NSMO.

    OUTPUTS:

       Tplot variable "Shape_PAD": store shape parameters for two directions, as well
           as the shape parameter for trapped population, spacecraft potentials,
           min/max pitch angle range to check if the PA coverage is enough

       Tplot variable "EFlux_ratio": store the flux ratio for two directions

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 10:14:21 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33407 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_shape_par_pad_l2_3pa.pro $

    CREATED BY:    Shaosui Xu  12-09-17

(See projects/maven/swea/swe_shape_par_pad_l2_3pa.pro)

## SWE_SNAP_COMMON

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

    COMMON BLOCK:   swe_snap_common
    PURPOSE:
      Common block for swe_snap_layout.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-08-03 16:50:48 -0700 (Mon, 03 Aug 2020) $
     $LastChangedRevision: 28981 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_snap_common.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/swea/swe_snap_common.pro)

## SWE_SNAP_LAYOUT

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

    PROCEDURE:   swe_snap_layout
    PURPOSE:
      Puts snapshot windows in convenient, non-overlapping locations,
      depending on display hardware.  These layouts are only recognized
      by the SWEA snapshot routines.  This routine has no effect unless
      a non-zero layout is specified, and you can only do that by calling
      this routine.  It is perfectly safe to simply ignore the existence
      of this routine.  It is admittedly only useful to the author.

      See win.pro for details on how the configuration structures are
      used to create and place windows.

      UPDATE: This routine is now obsolete.  The snapshot routines have
      been modified to use win to place snapshot windows in logically
      convenient locations.

    USAGE:
      swe_snap_layout, layout

    INPUTS:
           layout:        Integer specifying the layout:

                            0 --> Default.  No fixed window positions.
                            1 --> Macbook 1440x900 (below) with Dell 5120x1440 (above)
                            2 --> Macbook 1440x900 (below) with twin Dell 2560x1440 (left, right)
                            3 --> Macbook 1440x900 (below) with Dell 2560x1440 (above)

    KEYWORDS:

           HOME:          Equivalent to LAYOUT=3.

           WORK:          Equivalent to LAYOUT=2.

           WORK2:         Equivalent to LAYOUT=1.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-14 11:40:53 -0700 (Thu, 14 Jul 2022) $
     $LastChangedRevision: 30933 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_snap_layout.pro $

    CREATED BY:    David L. Mitchell  07-24-12

(See projects/maven/swea/swe_snap_layout.pro)

## SWE_SNAP_OPTIONS

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

    PROCEDURE:   swe_snap_options
    PURPOSE:
      Stores a structure of SWEA snapshot keyword options and provides
      a mechanism for changing those options.  Keywords set by this
      routine are persistent defaults in the SWEA snapshot 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:
      swe_snap_options, key

    INPUTS:
           key:           Structure containing keyword(s) for any of the SWEA
                          snapshot routines (engy, pad, 3d).  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-02 10:38:37 -0800 (Tue, 02 Mar 2021) $
     $LastChangedRevision: 29725 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_snap_options.pro $

(See projects/maven/swea/swe_snap_options.pro)

## SWE_SWI_CC_SNAP

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

    FUNCTION:   swe_swi_cc_snap
    PURPOSE:
      Gets cross calibration factor from SWE-SWI density ratio.

    USAGE:
      swe_swi_cc_snap
    INPUTS:
       None.      Data are selected from tplot window.

    KEYWORDS:
       NRANGES:   Number of time ranges to select.

       CCAL:      Cross calibration factors.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-08-02 11:15:31 -0700 (Wed, 02 Aug 2023) $
     $LastChangedRevision: 31976 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_swi_cc_snap.pro $

    CREATED BY:	David L. Mitchell, some time in 2014

(See projects/maven/swea/swe_swi_cc_snap.pro)

## SWE_TESTPULSER_MODEL

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

    PROCEDURE:   swe_testpulser_model
    PURPOSE:
      Creates SWEA Test Pulser Model and generates test pulser signatures
      in the three main data products (APID's A0, A2, A4).  The model is
      an analytic approximation to the measured test pulser signal.

    USAGE:
      swe_testpulser_model

    INPUTS:

    KEYWORDS:

           GROUP:        Group parameter (g) that controls energy bin
                         averaging for A0 and A2 products.  Does not
                         affect A4.

                         g = 0,1,2 corresponds to averaging 1, 2, or 4
                         adjacent energy channels.

           PAM:          Pitch angle map structure specifying the anode and deflector
                         bins comprising the PAD.  0 < andx < 15 ; 0 < dndx < 5.

                           pam = {andx:intarr(16), dndx:intarr(16)}

           RESULT:       Structure to hold A0, A2, and A4 test pulser
                         models.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-04-07 20:05:19 -0700 (Mon, 07 Apr 2014) $
     $LastChangedRevision: 14775 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/swe_testpulser_model.pro $

    CREATED BY:    David L. Mitchell  05-28-13
    FILE: swe_testpulser_model.pro
    VERSION:   1.0

(See projects/maven/swea/swe_testpulser_model.pro)

## TIMEFIT

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

    PROCEDURE:   timefit
    PURPOSE:
      Given an input time array or tplot variable name, sets the tplot time window to span
      the range of times in the array or tplot variable.

    USAGE:
      timefit, time, var=var

    INPUTS:
           time:      If this is a scalar string or integer, it's interpreted as
                      a tplot variable name or number, from which the time is
                      extracted.  If this is an array, it's interpreted as an
                      array of times, in any format accepted by time_double().

                      If all the times are identical and if keyword PAD
                      is not set, then a one hour interval centered on
                      that time is set.

    KEYWORDS:

           VAR:       Tplot variable name/number.  OBSOLETE, but retained for
                      backward compatibility.  If VAR is set, then time input
                      is ignored.

           PAD:       Amount of time to pad on either end of the time
                      span.  Default units are seconds.

           MIN:       PAD units are minutes.

           HOUR:      PAD units are hours.

           DAY:       PAD units are days.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-12-15 12:58:34 -0800 (Tue, 15 Dec 2020) $
     $LastChangedRevision: 29488 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/timefit.pro $

    CREATED BY:	David L. Mitchell  07-06-14

(See projects/maven/swea/timefit.pro)

## TOPOMTRX

[Previous Routine] [List of Routines]

    PROCEDURE:   topomtrx

    PURPOSE: This routine provides topology matrix or a table of topology
             for 6 given dimensions, defined by shape parameters, voids,
             and PAD info, which are:
                      0 - upward shape: 0: phe, 1: swe, 2:nan
                      1 - downward shape: 0: phe, 1: swe, 2:nan
                      2 - void: 0: yes, 1: no, 2:nan
                      3 - upward PAD: 0: not loss cone, 1: loss cone, 2:nan
                      4 - downward PAD: 0: not loss cone, 1: loss cone, 2:nan
                      5 - day/night: currently not used
             8 topology results are provided:
                      0 Unknown
                      1 Dayside Closed
                      2 Day-Night Closed
                      3 Night Closed -- Trapped/two-sided loss cone
                      4 Night CLosed -- Void
                      5 Day Open
                      6 Night Open
                      7 Draped

    USAGE:
      result = topomtrx()

    INPUTS:
           None

    KEYWORDS:
           None

     $LastChangedBy: xussui $
     $LastChangedDate: 2018-11-29 15:53:18 -0800 (Thu, 29 Nov 2018) $
     $LastChangedRevision: 26186 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/swea/topomtrx.pro $

    CREATED BY:    Shaosui Xu, 11/03/2017
    FILE: topomtrx.pro

(See projects/maven/swea/topomtrx.pro)