;--------------------------------------------------------------------
; MAVEN SWEA Crib
;
; Additional information for all procedures and functions can be
; displayed using doc_library.
;
; $LastChangedBy: dmitchell $
; $LastChangedDate: 2017-09-13 16:15:33 -0700 (Wed, 13 Sep 2017) $
; $LastChangedRevision: 23961 $
; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_1/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:
timespan, 'yyyy-mm-dd/hh:mm:ss', number_of_days
timespan, ['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.
mvn_spice_load, /download
; Step 3: Load data. This uses the time span from Step 1. You can
; and should load data from multiple instruments without
; repeating the first two steps. For example:
mvn_swe_load_l2, /spec, /pad
mvn_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. All of this is done automatically based on the
; time span and data type. Same goes for SPICE.
; Step 4: 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!
mvn_scpot
; Step 5+: Work with the data as you wish. When you want to go to
; a different time span, you must repeat steps 1-4.
; 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:
doc_library, 'routine_name'
; Load SWEA L0 data into a common block
mvn_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:
mvn_swe_load_l2
; 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.
;
; (I recommend that you load burst data in this way.)
mvn_swe_load_l2, /spec ; load SPEC survey data over the full range
smaller_trange = ['2014-12-10/10','2014-12-10/12']
mvn_swe_load_l2, smaller_trange, /pad, /noerase ; PAD survey data
mvn_swe_load_l2, smaller_trange, /pad, /burst, /noerase ; PAD burst data
; Summary plot. Loads ephemeris data and includes a panel for spacecraft
; altitude (default is aerodetic). Orbit numbers appear along the time
; axis.
;
; Many optional keywords for plotting additional panels.
; Use doc_library for details.
mvn_swe_sciplot, /sun, /sc_pot
; 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.
mvn_sundir, frame='swea', /polar, pans=pans
; Determine the RAM direction in spacecraft coordinates
; Requires SPICE. The RAM direction is calculated with respect to
; the IAU_MARS frame (planetocentric, body-fixed).
;
; Use keyword FRAME to calculate the RAM direction in any MAVEN
; frame recognized by SPICE. (Keyword APP is shorthand for
; FRAME='MAVEN_APP'.)
mvn_ramdir, pans=pans
; 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. This
; corrects for scattered electrons.
mvn_swe_n1d, /mb, pans=pans
; Estimate electron density and temperature from 1D moments. Works in
; the post-shock region, where the distribution is not Maxwellian.
; No correction for scattered electrons. (This is the default for
; key parameters.)
mvn_swe_n1d, /mom, pans=pans
; 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).
mvn_swe_pad_resample, nbins=128., erange=[100., 150.], /norm, /mask, /silent
; Calculate pitch angle distributions from 3D distributions
mvn_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.)
mvn_swe_pad_restore
; Snapshots selected by the cursor in the tplot window
; 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.
; Set the BURST keyword to show burst data instead of survey data.
swe_engy_snap,/mom,/fixy,spec=spec
swe_pad_snap,energy=130,pad=pad
swe_3d_snap,/spec,/symdir,energy=130,ddd=ddd,smo=[5,1,1]
;
; 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.)
ddd = mvn_swe_get3d(time, units='eflux')
pad = mvn_swe_getpad(time)
spec = mvn_swe_getspec(time)
; 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:
mvn_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:
ddd = mvn_swe_get3d(time, units='eflux', /shiftpot)
pad = mvn_swe_getpad(time, /shiftpot)
spec = mvn_swe_getspec(time, /shiftpot)
swe_engy_snap,/mom,/fixy,spec=spec,/shiftpot
swe_pad_snap,energy=130,pad=pad,/shiftpot
swe_3d_snap,/spec,/symdir,energy=130,ddd=ddd,smo=[5,1,1],/shiftpot
;
; Visualizing the orbit and spacecraft location
; 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.
;
; Ephemeris data are updated daily at 3:30 am Pacific.
maven_orbit_tplot,/loadonly
; Plot snapshots of the orbit in three orthogonal MSO planes.
; Optionally plot the orbit in cylintrical 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.
maven_orbit_snap