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

Last modified: Wed Sep 10 18:16:51 2025.

# Directory Listing of Routines

# projects/maven/sta/l2analysis/flow_vectors

- MVN_STA_FLOW

# Routine Descriptions

## MVN_STA_FLOW

[List of Routines]

    Crib to get STATIC flow information. Working progress. Routine produces flow vectors in MSO frame.

    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.

    UPDATES:
    2024-03-26: CMF: STATIC apid is now adde to the tplot variable names produced, so that the flow vector can be derived from multiple apids in
     the same session.

    .r /Users/cmfowler/IDL/STATIC_routines/Flow_routines/mvn_sta_flow.pro

(See projects/maven/sta/l2analysis/flow_vectors/mvn_sta_flow.pro)