This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 20 10:37:44 2023.
Crib to get STATIC flow information. Working progress. Routine produces flow vectors in MSO frame.
Note: routine currently only looks for d1 data; but this comes down most of the time, so should be ok for now.
This routine will check that SPICE kernels exist such that STATIC pointing information can be rotated to the MSO frame
at each timestep, using mvn_sta_ck_check. If not loaded, the routine will load them using mvn_spice_kernels(/load), based on the set values
of timespan.
This routine uses j_4d, which corrects for sc potential if it is present in the STATIC common blocks. By default, the L2 STATIC data contain the
sc potential (as estimated from STATIC). This tends to work well through periapsis in the ionosphere, but STATIC cannot determine the sc potential
when it is positive (ie at high altitudes in sunlight). In such cases, there is currently no correction applied.
INPUTS:
Load in STATIC ce, cf, d0 or d1 data into tplot and IDL. Use mvn_sta_l2_load, sta_apid=sta_apid.
sta_apid: the STATIC data product to use, as a string. Choose from 'ce', 'cf', 'd0', 'd1'.
OUTPUTS:
tplot variables: containing the MSO x, y, z fluxes for various ion species. Units are #/cm^2/s. Each tplot variable has the
AMU mass number appended to it. Note that there are only 8 mass bins within the d0/d1 data products, so mass
resolution is coarse.
"correction_factor": the size of the sc velocity correction factor, which can be compared to the ion flux and/or velocity.
"correction_flag": flags when the sc velocity correction is a significant fraction of the derived ion flux / velocity, and may
result in large errors. 0 = no flag, 1 = sc velocity correction is significant, defined as flux (or velocity)/correction factor < sc_cor_flag
sc_cor_flag is a keyword, with a default value of 2.
KEYWORDS:
trange: two element double array with start and stop times. If not set, routine will go over the entire loaded data, but this
may take a while.
Set /clearspice to clear the loaded SPICE kernels in IDL memory.
Default is to LEAVE the loaded SPICE kernels in IDL memory.
Set /kms to calculate flow in units of km/s.
Set /flux to calculate flow in units of #/cm^2/s.
If neither /kms nor /flux are set, the default is to set /kms.
species: there are several ions with pre-set mass parameters; enter the following strings (case independent):
'H', 'He', 'O', 'O2' or 'CO2'. If set, you don't need to set mrange or m_int - these are set for you. The species input overwrites
the mrange and m_int keywords.
mrange: [a,b]: use this keyword to specify the mass range for which flow velocities are calculated for.
Each mass range will have its own tplot variable created. If not set, all masses are used.
Some additional notes:
STATIC d0 and d1 data have 8 mass bins centered on the following AMU values. The following options are allowed for the
mass keyword:
mass = 1.09 AMU
= 2.23 AMU
= 4.67 AMU
= 9.42 AMU
= 17.14 AMU
= 30.57 AMU
= 42.42 AMU
= 62.53 AMU
STATIC ce and cf data have 16 mass bins (more mass resolution), but are only available in ~2015. After ~2015, at least d0
data should be available all of time (and d1 data should be available most of the time).
m_int: assumed AMU value to calculate flow. If not set, mean of mrange is used.
erange: [a,b]: energy range to look at in eV. If not set, full energy range is used.
Set /sc_vel to correct for spaccraft velocity relative to Mars (ie, move from spacecraft frame to Mars frame). When set, the routine
will use SPICE to obtain the spacecraft velocity (in the MSO corrdinate system). For ion velocity, the spacecraft velocity is subtracted
from the ion velocity in the spacecraft frame. For particle flux, j' = j - n*sc_vel; ie, flux in the Mars frame is equal to flux in the
spacecraft frame minus (density * spacecraft velocity).
### IMPORTANT ### as of 2019-11-07, the code uses n_4d to calculate density when correcting the number flux for sc velocity. This may not be
correct at lower altitudes when the ion distribution becomes a beam. CMF needs to adjust code to use L3 densities, once these are
available.
BINS: bytarr(ne,na), optional, energy/angle bins to be included in the array for integration
0,1=exclude,include
Default is to include all bins if not set.
ne = dat.energy (number of energy bins)
nb = dat.nbins (number of anode-deflector bins)
When set, data=dat.dat * bins. Zero elements do not contribute to the flux calculation.
sc_cor_flag: the value used to determine whether corrections for sc velocity are significant compared to derived ion fluxes or velocities. A flag is
set when flux (or velocity)/correction factor < sc_cor_flag.
The default value of sc_cor_flag is 2, if not set.
qc: set /qc if you have Mike Chaffins qualcolors installed. If not, leave, and the routine will use the current color table.
NOTES:
d0 and d1 data are large - don't try to load too many days at once, unless you have lots of RAM (lots means >= 16 Gb).
This routine will load in SPICE kernels for co-ordinate rotation, using mvn-spice-kernels. It will then remove them from IDL
memory once run. Use the above keywords to change whether these actions occur. The routine assumes that timespan has been set by the user.
The 8 mass bins in d0/d1 are centered on:
1.09088, 2.22833, 4.67166, 9.41619, 17.1449, 30.5701, 42.4226, 62.5310
EGS:
timespan, '2019-02-03', 1.
mvn_sta_l2_load, sta_apid=['d1'], /tplot_vars_create
kk = mvn_spice_kernels(/load) ;load SPICE kernels based on timespan
mvn_sta_flow, /flux, species='O', sta_apid='d1', spicekernels=kk ;calculate O+ flow vectors for all available timestamps. SPICE is loaded before hand.
timespan, '2019-02-03', 1.
mvn_sta_l2_load, sta_apid=['d1'], /tplot_vars_create
ctime, tt ;for now, this routine requires a time range input as flow calculations take a long time on an entire day.
mvn_sta_flow, /flux, species='O2', sta_apid='d1', trange=tt ;calculate O2+ vectors for selected time range only. SPICE is loaded within the routine.
.r /Users/cmfowler/IDL/STATIC_routines/Flow_routines/mvn_sta_flow.pro
(See projects/maven/sta/l2analysis/flow_vectors/mvn_sta_flow.pro)