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

Last modified: Fri Sep 26 18:17:39 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/particles/ESA

- CLEAR_ESA_COMMON_BLOCKS
- THM_CRIB_ESA_DIST2SCPOT
- THM_ESA_CMN_L2CONCAT
  concatenates two THEMIS ESA L2 data structures
- THM_ESA_CMN_L2READ.PRO
  Inputs a THEMIS ESA common block structure from an L2 CDF.
- THM_ESA_CMN_L2TCLIP
  applies a trange to a THEMIS ESA L2 structure
- THM_ESA_CMN_L2VARARR
  Returns an array with common block variable names for the input
- RTBIS_2X
  Simple bisection routine,
- THM_ESA_DENS2SCPOT
  Estimates the SC potential from electrona and ions, by choosing the
- RTBIS
  Simple bisection routine,
- THM_ESA_DFRAC2SCPOT
  Estimates the SC potential from electrona and ions, by choosing the
- THM_ESA_DIST2BZ
  For a given probe and date, estimates the SC potential from PEEF
- THM_ESA_DIST2BZ_ANGLE
  Estimates the angle between the direction of the electron
- THM_ESA_DIST2BZ_VSE
  Finds a pitch angle for an electron distribution, by calculating
- THM_ESA_DIST2SCPOT
  Estimates the SC potential from an electron sepctrum, by comparing
- THM_ESA_DUMP
- THM_ESA_ENERGY_EXTRAPOLATE
- THM_ESA_EST_DENS2SCPOT
  For a given probe and date, estimates the SC potential from PEER
- THM_ESA_EST_DFRAC2SCPOT
  For a given probe and date, estimates the SC potential from PEER and PEIR
- THM_ESA_EST_DIST2SCPOT
  For a given probe and date, estimates the SC potential from PEER
- THM_ESA_EST_DIST2SCPOT2
  For a given probe and date, estimates the SC potential from PEER
- THM_ESA_QUALITY_FLAGS[1]
- THM_ESA_QUALITY_FLAGS[2]
- THM_ESA_TEST_SPEC3D2
  Wrapper for spec3d2, plots PEEF, PEER, PEEB data; the user clicks on
- THM_LOAD_L2_ESADIST
  Loads THEMIS ESA L2 data for a given file(s), or time_range
- THM_LOAD_PXXM_POT4ESA
  loads the pxxm_pot variable for ESA processing, performs a time

# Routine Descriptions

## CLEAR_ESA_COMMON_BLOCKS

[Next Routine] [List of Routines]

    Procedure:	clear_esa_common_blocks

    Purpose:	Clears common blocks used in esa_pkt routines, to
                   avoid using old data to create plots or L2 files
     jmm, jimm@ssl.berkeley.edu, 12-dec-2007
     $LastChangedBy: pcruce $
     $LastChangedDate: 2012-02-07 13:47:46 -0800 (Tue, 07 Feb 2012) $
     $LastChangedRevision: 9692 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/clear_esa_common_blocks.pro $

(See projects/themis/spacecraft/particles/ESA/clear_esa_common_blocks.pro)

## RTBIS

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

    NAME:
     rtbis
    PURPOSE:
     Simple bisection routine,
    CALLING SEQUENCE:
     x = rtbis(func_in, x1, x2, xacc=xacc, jmax=jmax)
    INPUT:
     func_in = an input function -- the answer will give func_in(x) = 0.0
     x1 = a lower limit
     x2 = an upper limit
    KEYWORDS:
     xacc = the accuracy, default is 1.0e-6
     jmax = max. number of iterations, the default is 40
    HISTORY:
     Copied from Numerical Recipies, 12-feb-2015, jmm,
     jimm@ssl.berkeley.edu

(See projects/themis/spacecraft/particles/ESA/thm_esa_dfrac2scpot.pro)

## RTBIS_2X

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

    NAME:
     rtbis_2x
    PURPOSE:
     Simple bisection routine,
    CALLING SEQUENCE:
     x = rtbis_2x(func_in, x1, x2, xacc=xacc, jmax=jmax)
    INPUT:
     func_in = an input function -- the answer will give func_in(x) = 0.0
     x1 = a lower limit
     x2 = an upper limit
    KEYWORDS:
     xacc = the accuracy, default is 1.0e-6
     jmax = max. number of iterations, the default is 40
    HISTORY:
     Copied from Numerical Recipies, 12-feb-2015, jmm,
     jimm@ssl.berkeley.edu

(See projects/themis/spacecraft/particles/ESA/thm_esa_dens2scpot.pro)

## THM_CRIB_ESA_DIST2SCPOT

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

    THM_ESA_DIST2SCPOT

    The program THM_ESA_DIST2SCPOT estimates the spacecraft potential
    from the electron distribution by lookng for photoelectrons at low
    energies. It estimates potential by comparing the slope of the low
    energy electron distribution to the expected slope of secondary
    electrons. (The slope of the secondary electron distribution is
    approximately -2.0, see McFadden etal. 2008SSRv..141..477M)

    For a given time interval, the procedure is as follows:

    1) Calculate the slope of the electron distribution. The slope of the
    distribution between the energies E0, and E1 is given by:

    M = (log(F1)-log(F0))/(log(E1)-log(E0),

    where F is the differential electron energy flux in eV/sec/cm^2/eV.

    2) Next we Compare the low-energy slope with the expected slope of
    secondary electrons, which is estimated to be between -2.0 at 8 eV
    and -4.0 at 50 eV. (These numbers are empirical, except for the lower
    limit). The upper limit of the photoelectron part of the distribution
    is estimated to be the highest energy for which the slope is steeper
    than the secondary electron slope.

    3) Also, the electron distribution has to exhibit at least two
    distinct peaks, a low-energy peak must be present with electron flux
    greater than 3.0e7 eV/sec/cm^2/eV, and a higher energy peak with
    electron flux greater than 1.0e-3 times the value of the overall peak
    of the distribution. (These parameters are the default values, and
    can be changed via the photoelectron_threshold and noise_threshold.)

    4) Since slopes are calculated between energy values, the estimate
    for M is at the midpoint between E0 and E1. We 'unquantize' by an
    amount that depends on the difference between the actual slope and
    the secondary electron slope, so that the final value of the
    estimated potential is: ;

    SC_POT = E0+(E1-E0)*(1-M/2)/(1-M)

    For M=2, the lowest possible value, SC_POT = E0. For an infinite
    slope, SC_POT is the midpoint between E0 and E1.

    5) If the test for low energy photoelectrons fails, i,e, the
    distribution does not show two peaks, OR the low energy, possible
    photoelectron peak is below 3.0e7, OR the low energy slope is not
    steeper that the secondary electron slope, OR if there is a high
    energy peak, but one that is too small. Then the value for the SC_POT
    estimate is set to the lowest energy in the electron distribution.

    	Batch File: THM_CRIB_ESA_DIST2SCPOT

    	Purpose:  Demonstrates the use of THM_ESA_EST_DIST2SCPOT.
    	The program THM_ESA_EST_DIST2SCPOT estimates the spacecraft
    	potential using the ESA electron distribution. The SC
    	potential is estimated by comparison of the slope of the low
    	energy electron flux with the expected slope of secondary electrons

    	Calling Sequence:
    	.run thm_crib_esa_dist2scpot, or using cut-and-paste.

    	Arguements:  None.

    	Notes: None.

     $LastChangedBy: jimm $
     $LastChangedDate: 2015-07-24 15:57:59 -0700 (Fri, 24 Jul 2015) $
     $LastChangedRevision: 18252 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_crib_esa_dist2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_crib_esa_dist2scpot.pro)

## THM_ESA_CMN_L2CONCAT

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

    NAME:
     thm_esa_cmn_l2concat
    PURPOSE:
     concatenates two THEMIS ESA L2 data structures
    CALLING SEQUENCE:
     dat = thm_esa_cmn_l2concat(dat1, dat2)
    INPUT:
     cmn_dat = a structrue with the data:
       PROJECT_NAME    STRING    'THEMIS'
       SPACECRAFT      STRING    'c'
       DATA_NAME       STRING    'IESA 3D Reduced'
       APID            INT           1109 (Apids in filenames are hex values)
       UNITS_NAME      STRING    'eflux'
       UNITS_PROCEDURE STRING    'thm_convert_esa_units'
       VALID           BYTE      Array[ntimes]
       TIME            DOUBLE    Array[ntimes]
       END_TIME        DOUBLE    Array[ntimes]
       DELTA_T         DOUBLE    Array[ntimes]
       INTEG_T         DOUBLE    Array[ntimes]
       DT_ARR          FLOAT     Array[ntimes,88, 8]
       CONFIG1         BYTE      Array[ntimes]
       CONFIG2         BYTE      Array[ntimes]
       AN_IND          INT       Array[ntimes]
       EN_IND          INT       Array[ntimes]
       MODE            INT       Array[ntimes]
       NENERGY         INT       Array[8] ;there are 8 different possible
                                          ;modes
       ENERGY          FLOAT     Array[32, 8]
       DENERGY         FLOAT     Array[32, 8]
       NBINS           INT       Array[8]
       THETA           FLOAT     Array[32, 88, 8]
       DTHETA          FLOAT     Array[32, 88, 8]
       PHI             FLOAT     Array[32, 88, 8]
       DPHI            FLOAT     Array[32, 88, 8]
       DOMEGA          FLOAT     Array[32, 88, 8]
       GF              FLOAT     Array[32, 88, 8]
       ECLIPSE_DPHI    DOUBLE    Array[ntimes]
       PHI_OFFSET      FLOAT    Array[ntimes]
       GEOM_FACTOR     FLOAT        0.00153000
       DEAD            FLOAT       1.70000e-07
       MASS            FLOAT         0.0104389
       CHARGE          FLOAT           1.00000
       SC_POT          FLOAT     Array[ntimes]
       MAGF            FLOAT     Array[ntimes, 3]
       BKG_PSE         FLOAT     Array[ntimes]
       BKG_PEI         FLOAT     Array[ntimes]
       BKG             FLOAT     Array[ntimes]
       BKG_ARR         FLOAT     Array[32, 88, 8]
    Added in this program
       BINS            BYTE      Array[ntimes, 32, 88]
       EFF             FLOAT     Array[ntimes, 32, 88]
       EFLUX           FLOAT     Array[ntimes, 32, 88];
       NENERGY_MODES   BYTE         8
       NBIN_MODES      BYTE         8
       DATA_QUALITY    INT       Array[ntimes]
    OUTPUT:
     dat = a single structure concatenated
    HISTORY:
     Hacked from FAST ESA version 24-Oct-2022, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2022-11-08 11:44:09 -0800 (Tue, 08 Nov 2022) $
     $LastChangedRevision: 31250 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2concat.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2concat.pro)

## THM_ESA_CMN_L2READ.PRO

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

    NAME:
     thm_esa_cmn_l2read.pro
    PURPOSE:
     Inputs a THEMIS ESA common block structure from an L2 CDF.
    CALLING SEQUENCE:
     cmn_dat = thm_esa_cmn_l2load(filename, trange = trange, cdf_info=cdf_info)
    INPUT:
     filename = the input filename
    OUTPUT:
     cmn_dat = a structrue with the data:
    e.g.,
       PROJECT_NAME    STRING    'THEMIS'
       SPACECRAFT      STRING    'c'
       DATA_NAME       STRING    'IESA 3D Reduced'
       APID            INT           1109 (Apids in filenames are hex values)
       UNITS_NAME      STRING    'eflux'
       UNITS_PROCEDURE STRING    'thm_convert_esa_units'
       VALID           BYTE      Array[ntimes]
       TIME            DOUBLE    Array[ntimes]
       END_TIME        DOUBLE    Array[ntimes]
       DELTA_T         DOUBLE    Array[ntimes]
       INTEG_T         DOUBLE    Array[ntimes]
       DT_ARR          FLOAT     Array[ntimes,88, 8]
       CONFIG1         BYTE      Array[ntimes]
       CONFIG2         BYTE      Array[ntimes]
       AN_IND          INT       Array[ntimes]
       EN_IND          INT       Array[ntimes]
       MODE            INT       Array[ntimes]
       NENERGY         INT       Array[8] ;there are 8 different possible
                                          ;modes for reduced electrons
       ENERGY          FLOAT     Array[32, 8]
       DENERGY         FLOAT     Array[32, 8]
       NBINS           INT       Array[8]
       THETA           FLOAT     Array[32, 88, 8]
       DTHETA          FLOAT     Array[32, 88, 8]
       PHI             FLOAT     Array[32, 88, 8]
       DPHI            FLOAT     Array[32, 88, 8]
       DOMEGA          FLOAT     Array[32, 88, 8]
       GF              FLOAT     Array[32, 88, 8]
       ECLIPSE_DPHI    DOUBLE    Array[ntimes]
       PHI_OFFSET      FLOAT    Array[ntimes]
       GEOM_FACTOR     FLOAT        0.00153000
       DEAD            FLOAT       1.70000e-07
       MASS            FLOAT         0.0104389
       CHARGE          FLOAT           1.00000
       SC_POT          FLOAT     Array[ntimes]
       MAGF            FLOAT     Array[ntimes, 3]
       BKG_PSE         FLOAT     Array[ntimes]
       BKG_PEI         FLOAT     Array[ntimes]
       BKG             FLOAT     Array[ntimes]
       BKG_ARR         FLOAT     Array[32, 88, 8]
       DATA_LEVEL      STRING    'Level 2'
       BINS            BYTE      Array[ntimes, 32, 88]
       EFF             FLOAT     Array[ntimes, 32, 88]
       EFLUX           FLOAT     Array[ntimes, 32, 88]
       NENERGY_MODES   BYTE         8
       NBIN_MODES      BYTE         8
       DATA_QUALITY    INT       Array[ntimes]
    KEYWORDS:
     trange = if set, then only input data for that time range, the first
              step would be to input the record times and then obtain a
              record range to input.
     cdf_info = the full structure from CDF_LOAD_VARS2
     gatt = the global attributes from the CDF file
     vatt = the variable attributes for the variables included in the output
    HISTORY:
     2022-10-31, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2022-11-07 12:26:32 -0800 (Mon, 07 Nov 2022) $
     $LastChangedRevision: 31243 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2read.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2read.pro)

## THM_ESA_CMN_L2TCLIP

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

    NAME:
     thm_esa_cmn_l2tclip
    PURPOSE:
     applies a trange to a THEMIS ESA L2 structure
    CALLING SEQUENCE:
     dat = thm_esa_cmn_l2tclip(dat, trange)
    INPUT:
     dat1 = a THEMIS ESA L2 3D data structure: e.g.,
    OUTPUT:
     dat = structure with data only in the input time range
    NOTES:
     Only will work if the record varying arrays are 5D or less
    HISTORY:
     8-Nov-2022 jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2022-11-08 11:43:51 -0800 (Tue, 08 Nov 2022) $
     $LastChangedRevision: 31249 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2tclip.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2tclip.pro)

## THM_ESA_CMN_L2VARARR

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

    NAME:
     thm_esa_cmn_l2vararr
    PURPOSE:
     Returns an array with common block variable names for the input
     data_name.
    CALLING SEQUENCE:
     vars = thm_esa_cmn_l2vararr(data_name)
    INPUT:
     data_name = the data_name for the data type; It turns out that this
                 is unused since all of the L2 structures have the same
                 variables
    OUTPUT:
     vars = a 3, N array with common block variable names for the input
     data_name, with three columns, one is the common block name, the second is
     the name in the CDF file, the third is 'Y' or 'N' for record
     variance.
    HISTORY:
     24-Oct-2022, jmm, Hacked from fa_esa_cmn_l2vararr
     $LastChangedBy: jimm $
     $LastChangedDate: 2023-10-30 16:00:06 -0700 (Mon, 30 Oct 2023) $
     $LastChangedRevision: 32212 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2vararr.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_cmn_l2vararr.pro)

## THM_ESA_DENS2SCPOT

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

    NAME:
     thm_esa_dens2scpot
    CALLING SEQUENCE:
     scpot = thm_esa_dens2scpot(edat, idat)
    PURPOSE:
     Estimates the SC potential from electrona and ions, by choosing the
     potential that gives ion density = electron density
    INPUT:
     edat = 3d data electron structure filled by themis routines get_th?_p???
     idat = 3d data ion structure filled by themis routines get_th?_p???
     use_n3dnew = if set, use n_3d_new.pro to get densities
     expected_fraction = if set, this is the value of electron density
     divided by ion density expected. The default is 1.75, that is we
     expect the electron density to be about 1,75 times the ion density.
    KEYWORDS:
    HISTORY:
     2025-07-31, jmm, Changed to calculate using density versus density
     from SCP,  jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2025-07-30 14:38:14 -0700 (Wed, 30 Jul 2025) $
     $LastChangedRevision: 33513 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_dens2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dens2scpot.pro)

## THM_ESA_DFRAC2SCPOT

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

    NAME:
     thm_esa_dfrac2scpot
    CALLING SEQUENCE:
     scpot = thm_esa_dfrac2scpot(edat, idat)
    PURPOSE:
     Estimates the SC potential from electrona and ions, by choosing the
     potential that gives ion density = electron density
    INPUT:
     edat = 3d data electron structure filled by themis routines get_th?_p???
     idat = 3d data ion structure filled by themis routines get_th?_p???
     use_n3dnew = if set, use n_3d_new.pro to get densities
     expected_fraction = if set, this is the value of electron density
     divided by ion density expected. The default is 1.75, that is we
     expect the electron density to be about 1,75 times the ion density.
    KEYWORDS:
    HISTORY:
     2023-02-01, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2025-03-11 13:52:33 -0700 (Tue, 11 Mar 2025) $
     $LastChangedRevision: 33164 $
     $URL: $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dfrac2scpot.pro)

## THM_ESA_DIST2BZ

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

    NAME:
     thm_esa_dist2bz
    PURPOSE:
     For a given probe and date, estimates the SC potential from PEEF
     data, and plots it.
    CALLING SEQUENCE:
     thm_esa_dist2bz, date, probe, no_init = no_init, $
                      random_dp = random_dp, plot = plot
    INPUT:
     date = a date, e.g., '2008-01-05'
     probe = a probe, e.g., 'c'
    OUTPUT:
     a tplot variable 'th'+probe+'_dist2bz' is created
     If /random_dp is set, then date and probe are output
    KEYWORDS:
     trange = a time range
     no_init = if set, do not read in a new set of data
     random_dp = if set, the input date and probe are randomized, note
                 that this keyword is unused if no_init is set.
     use_ev = if set, use an average eignevector (from different energy
              bands) to get the theta (latitude) angle between the
              electron distribution direction, rather than the average
              theta
     phi_threshold = Good eigenvector values need to have an azimuthal
                    (phi) angle closer to atan(bx,by) than this value, in
                    degrees. Default is 30.0
    HISTORY:
     10-jun-2024, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dist2bz.pro)

## THM_ESA_DIST2BZ_ANGLE

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

    NAME:
     thm_esa_dist2bz_angle
    CALLING SEQUENCE:
     bz = thm_esa_dist2bz(data)
    PURPOSE:
     Estimates the angle between the direction of the electron
     distribution, and the Z (spin axis) axis sepctrum, by comparing the
     parallel and perpendicular values of pressure tensor eigenvalues.
     This function calls the function thm_esa_dist2bz_vse for different
     energy ranges.
    INPUT:
     data = 3d data structure filled by themis routines get_th?_p???
    KEYWORDS:
     theta_threshold = Only use energy bands for which the theta value is
                       closer to the median than this value, default is
                       3.0 degrees.
     nband_min = If there are fewer than this ok energy bands, thne no
                 solution, the default is 3.
     sim_threshold = If the two most similar eigenvalues are more than
                     this value apart, then discard this energy range
                     for this time interval. Default is 0.10 (10%)
     ani_threshold = If the most dissimilar eigenvaule is less than this
                     value different than the other two, then discard this
                     energy range for this time interval. Default is 0.20
                     (20%)
     av_theta = the average value of theta for the Ok energy bands, the
                output will be slightly different, and will be the value
                of theta calculated from the average of the eigenvectors
                for the ok energy bands.
     The idea here is that for the pressure tensor, there will be two very
     similar eigenvalues (p_parallel), and one dissimilar (p_perp). If
     p_par >> p_perp, then electron "cigar" distribution, if p_par <<
     p_perp, then "pancake" distribution. This will give us an angle,
     theta, for the field relative to the Z axis, and then Bz =
     tan(theta)*sqrt(Bx^2+By^2)/ Spin period resolution is needed to
     average out the azimuthat effects.
    HISTORY:
     Hacked from thm_dist2scpot.pro, 2024-06-04, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dist2bz_angle.pro)

## THM_ESA_DIST2BZ_VSE

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

    NAME:
     thm_esa_dist2bz_vse
    CALLING SEQUENCE:
     otp = thm_esa_dist2bz_vse(data)
    PURPOSE:
     Finds a pitch angle for an electron distribution, by calculating
     eigenvectors and eigenvalues for the distribution, using the pressure
     tensor.
     The idea here is that for the pressure tensor, there will be two very
     similar eigenvalues (p_parallel), and one dissimilar (p_perp). If
     p_par >> p_perp, then electron "cigar" distribution, if p_par <<
     p_perp, then "pancake" distribution. This will give us an angle,
     theta, for the field relative to the Z axis, and then Bz =
     tan(theta)*sqrt(Bx^2+By^2)/ Spin period resolution is needed to
     average out the azimuthal effects.
    INPUT:
     data = 3d data structure filled by themis routines get_th?_p???
    KEYWORDS:
     channel_range = the energy channels to use, the default is all
                     channels
     sim_threshold = If the two most similar eigenvalues are more than
                     this value apart, then discard this energy range
                     for this time interval. Default is 0.10 (10%)
     ani_threshold = If the most dissimilar eigenvaule is less than this
                     value different than the other two, then discard this
                     energy range for this time interval. Default is 0.20
                     (20%)
    HISTORY:
     Hacked from thm_dist2scpot.pro, 2024-06-04, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dist2bz_vse.pro)

## THM_ESA_DIST2SCPOT

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

    NAME:
     thm_esa_dist2scpot
    CALLING SEQUENCE:
     scpot = thm_esa_dist2scpot(data)
    PURPOSE:
     Estimates the SC potential from an electron sepctrum, by comparing
     the slope of the electron energy distribution with the slope that
     would be expected from secondary electrons.
    INPUT:
     data = 3d data structure filled by themis routines get_th?_p???
    KEYWORDS:
     pr_slope = if set, show some diagnostics prints of the slope of the
                distribution
     noise_threshold = values below Noise_threshold*max(flux) are
                       considered to be in noise, if there is a positive
                       slope, it is ignored. The default is 1.0e-3
     photoelectron_threshold = Only test for photoelctrons if the flux
                               is above this value, The default is 1.0e7
    HISTORY:
     Hacked from spec3d.pro, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2017-10-02 11:19:09 -0700 (Mon, 02 Oct 2017) $
     $LastChangedRevision: 24078 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_dist2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dist2scpot.pro)

## THM_ESA_DUMP

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

    Purpose:
      Helper function to store single array from specified
      structure tag as tplot variable(s)

    Arguments:
      ptr:  pointer to array of data structures
      name:  string of structure tag to use
      prefix:  string prefix of tplot var(s) to be created

(See projects/themis/spacecraft/particles/ESA/thm_esa_dump.pro)

## THM_ESA_ENERGY_EXTRAPOLATE

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

    PROCEDURE: thm_esa_energy_extrapolate
    PURPOSE:  Performs linear extrapolation of esa data to a new set of higher energies

    INPUTS:
      dist_data:
        The esa data structure on which the extrapolation should be performed.  (loaded by thm_part_dist_array)
    KEYWORDS:

      add_energy=add_energy : Adds these energies to the current set of energies for the particle data when extrapolating.
      lin_energy=lin_energy : Set this keyword to perform extrapolation on energy, not logarithmic.
      lin_counts=lin_counts: Set this keyword to perform extrapolation on counts, not logarithmic
      lsquadratic=lsquadratic: Set this keyword to perform least square quadratic extrapolation of count data(see interpol documentation in IDL help.)
      quadratic=quadratic: Set this keyword to perform quadratic extrapolation of count data.(see interpol documentation in IDL help.)
      lsquares=lsquares: Set this keyword to the number of bins that you want to use for least squares extrapolation of the count data(Uses poly_fit)
      spline=spline: Set this keyword to perform spline extrapolation of count data.(see interpol documentation in IDL help.)
      trange=trange: Set this keyword to a two element array specifying a subset of the data that the operation should be performed on.(Don't need to modify the whole thing with the same parameters)
      error=error:  Returns 1 if an error occurred.  Returns 0 if operation completed successfully.

      bin_select: set the bin numbers that you want to use in the extrapolation
    EXAMPLES:
     dist_data = thm_part_dist_array(probe='a',type='peef',trange=time_double(['2012-02-08/09','2012-02-08/12']))
     thm_part_conv_units,dist_data,error=e
     thm_esa_energy_extrapolate,dist_data,add_energy=[100000,70000,50000]

    NOTES:
      Removes the retrace bin from ESA modes that include retrace.

      $LastChangedBy: pcruce $
      $LastChangedDate: 2013-01-10 18:10:18 -0800 (Thu, 10 Jan 2013) $
      $LastChangedRevision: 11424 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_energy_extrapolate.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_energy_extrapolate.pro)

## THM_ESA_EST_DENS2SCPOT

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

    NAME:
     thm_esa_est_dens2scpot
    PURPOSE:
     For a given probe and date, estimates the SC potential from PEER
     data, and plots it.
    CALLING SEQUENCE:
     thm_esa_est_dens2scpot, date, probe, no_init = no_init, $
                             random_dp = random_dp, plot = plot
    INPUT:
     date = a date, e.g., '2008-01-05'
     probe = a probe, e.g., 'c'
    OUTPUT:
     a tplot variable 'th'+probe+'_est_scpot' is created
     If /random_dp is set, then date and probe are output
    KEYWORDS:
     trange = a time range
     no_init = if set, do not read in a new set of data
     random_dp = if set, the input date and probe are randomized, note
                 that this keyword is unused if no_init is set.
     plot = if set, plot a comparison of the estimated sc_pot wht the
            value obtained from the esa L2 cdf (originally from
            thm_load_esa_pot)
     use_n3dnew = if set, use n_3d_new.pro to get densities
    HISTORY:
     1-feb-2023, jmm, jimm@ssl.berkeley.edu
     Repurposed, now this prgram uses the electron density and not the
     electron to ion ratio, jmm, 28-jul-2025
     $LastChangedBy: jimm $
     $LastChangedDate: 2025-07-30 14:38:14 -0700 (Wed, 30 Jul 2025) $
     $LastChangedRevision: 33513 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_est_dens2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_est_dens2scpot.pro)

## THM_ESA_EST_DFRAC2SCPOT

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

    NAME:
     thm_esa_est_dfrac2scpot
    PURPOSE:
     For a given probe and date, estimates the SC potential from PEER and PEIR
     data, and plots it.
    CALLING SEQUENCE:
     thm_esa_est_dfrac2scpot, date, probe, no_init = no_init, $
                              random_dp = random_dp, plot = plot
    INPUT:
     date = a date, e.g., '2008-01-05'
     probe = a probe, e.g., 'c'
    OUTPUT:
     a tplot variable 'th'+probe+'_est_scpot' is created
     If /random_dp is set, then date and probe are output
    KEYWORDS:
     trange = a time range
     no_init = if set, do not read in a new set of data
     random_dp = if set, the input date and probe are randomized, note
                 that this keyword is unused if no_init is set.
     plot = if set, plot a comparison of the estimated sc_pot wht the
            value obtained from the esa L2 cdf (originally from
            thm_load_esa_pot)
     use_n3dnew = if set, use n_3d_new.pro to get densities
    HISTORY:
     1-feb-2023, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2023-02-06 15:08:13 -0800 (Mon, 06 Feb 2023) $
     $LastChangedRevision: 31478 $
     $URL: $

(See projects/themis/spacecraft/particles/ESA/thm_esa_est_dfrac2scpot.pro)

## THM_ESA_EST_DIST2SCPOT

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

    NAME:
     thm_esa_est_dist2scpot
    PURPOSE:
     For a given probe and date, estimates the SC potential from PEER
     data, and plots it.
    CALLING SEQUENCE:
     thm_esa_est_dist2scpot, date, probe, no_init = no_init, $
                              random_dp = random_dp, plot = plot
    INPUT:
     date = a date, e.g., '2008-01-05'
     probe = a probe, e.g., 'c'
    OUTPUT:
     a tplot variable 'th'+probe+'_est_scpot' is created
     If /random_dp is set, then date and probe are output
    KEYWORDS:
     trange = a time range
     no_init = if set, do not read in a new set of data
     random_dp = if set, the input date and probe are randomized, note
                 that this keyword is unused if no_init is set.
     plot = if set, plot a comparison of the estimated sc_pot wht the
            value obtained from the esa L2 cdf (originally from
            thm_load_esa_pot)
     esa_datatype = 'peef', 'peer', or 'peeb'; the default is 'peer'

    HISTORY:
     31-may-2015, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2017-10-02 11:19:09 -0700 (Mon, 02 Oct 2017) $
     $LastChangedRevision: 24078 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot.pro)

## THM_ESA_EST_DIST2SCPOT2

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

    NAME:
     thm_esa_est_dist2scpot2
    PURPOSE:
     For a given probe and date, estimates the SC potential from PEER
     data, and plots it. This differs from the original
     thm_esa_est_dist2scpot.pro in that it uses the "eyeball test"; it
     only checks byte-scaled eflux variables.
    CALLING SEQUENCE:
     thm_esa_est_dist2scpot2, date, probe, no_init = no_init, $
                              random_dp = random_dp, plot = plot
    INPUT:
     date = a date, e.g., '2008-01-05'
     probe = a probe, e.g., 'c'
    OUTPUT:
     a tplot variable 'th'+probe+'_est_scpot' is created
     If /random_dp is set, then date and probe are output
    KEYWORDS:
     trange = a time range
     no_init = if set, do not read in a new set of data
     random_dp = if set, the input date and probe are randomized, note
                 that this keyword is unused if no_init is set.
     plot = if set, plot a comparison of the estimated sc_pot with the
            value obtained from the esa L2 cdf (originally from
            thm_load_esa_pot)
     esa_datatype = 'peef', 'peer', or 'peeb'; the default is 'peer'
     dyellow = the value subtracted from the peak of the distribution to
            obtain the value below which we decide the photoelectron part
            ends. The default value is 40.
     yellow = the limit (0-255) where above this value, we assume that
              there are photo electrons in the scaled eflux
              spectrogram. This will give the potential; the default is
              205.
     lo_scpot = lower limit for the potential, default is to use the low
                energy limit of the data
     hi_scpot = upper limit for the potential, default is 100 V
     time_smooth_dt = if set, smooth the data in time, using this value
                      as smoothing time, default is no smoothing
     hsk_test = if the HSK data for hsk_ifgm_xy_raw and hsk_ifgm_zr_raw
                is below this value, set potential to low limit
     densmatch = if the potential is set to the low limit, because the
                 distribution is unsuitable (maybe not two maxima below
                 100 eV) then use thm_esa_dfrac2scpot for the potential.
     use_counts = if set, use the'en_counts' variable, and not
                  the 'en_flux' variable.
     slope_test = if set then the potential is set to the point at which
                  there is a maximum negative slope, if this value is
                  less than 30 V.
     sst_test = If set, if the SST electron total flux (thx_psef_tot) is
                greater than this value, then th SC potential is set to
                scplo. The default is to not use this test, but a good
                value, based on data for THE from 2017, looks like 5.0e4.
    NOTES:
     Here is a summary of the process:
     1) PEER data is the default. If the keyword /no_init is not set,
     Level 2 data is loaded for the input probe and date.
     2) Limits are set; by default, SCPLO is set to the lowest energy
     value in the data, but can be reset using the keyword
     lo_scpot. SCPHI has a default of 100 V, but can can be set using the
     keyword hi_scpot.
     3) If the hsk_test keyword is set, then FGM housekeeping data is
     used to determine where the sc_pot should be set to SCPLO. The
     calculation is expected to be unreliable when the variables
     'th(probe)_hsk_ifgm_xy_raw' and 'th(probe)_hsk_ifgm_zr_raw' have very
     low values. hsk_test = 75 is the value used for THEMIS ESA L2
     production. If the sst_test keyword is set, then the calculation is
     not good when the sst total electron variable is greater than this
     number. sst_test = 3e4 is the value used for THEMIS_ESA_L2.
     4) Next, the spectrum is bytescaled in log space, so that values are
     between 0 and 255.
     5) For each time interval, in order for photoelectrons to be
     expected, there has to be a local maximum in the spectrum at low
     energy, in one of the two lowest energy channels of the peer
     data. If there is no low energy maximum, or if this value is less
     than the 'yellow' value discussed in the next step, then there are no
     photoelectrons expected, and the potential is set to SCPLO.
     6) For each time interval, the spectrum is interpolated to a
     higher resolution energy grid (also in log space).
     7) For each time interval, a value of 'yellow' is chosen; this is
     the limit where above this value, we assume that there are low
     energy photo electrons in the scaled eflux spectrogram. There are
     two keywords, 'yellow' (default 205) and 'dyellow' (default 40). The
     value for each time interval is determined by the value of the low
     energy peak minus the dyellow value. For example, if the low energy
     bytescaled peak is a value of 240, then the photoelectron part of
     the distribution is set to 240-dyellow (approximately yellow on the
     typical plot color scale). The default is 40, so for this example,
     the cutoff for photoelectrons is then 200. But since the default
     value of the 'yellow' keyword is 205, then the cutoff is set to 205,
     and the potential is set to the energy value where the spectrum
     drops below the value of 205. The spectrum has to persist below this
     value for at least 10 points in the high resolution energy
     spectrum. If the value of the spectrum does not drop below 205, or
     is not below 205 for enough points, then it is assumed that there is
     no substantial photoelectron component, and the potential is set to
     SCPLO. (Note that the values of 205 and 40 were chosen using
     examples created by testing the estimates versus real SCPOT data for
     THEMIS A, D, and E for the first two weeks of January 2017.)
     8) If the keyword /slope_test is set and there is an estimate of
     scpot > SCPLO, then the potential is set to the point where the
     negative slope of the spectrum has a maximum value, if this value is
     less than 30 V. This is done to avoid very large estimates where
     the slope of the spectrum starts off very negative at low energy,
     but then there is a nearly flat but slightly decreasing slope at
     higher energy, which delays the descent of the spectrum to the 'yellow'
     value. This is the default for THEMIS L2 ESA file production.
     9) If the /densmatch keyword is set, and the estimated value of the
     potential is greater than the SCPHI limit, then the potential is
     adjusted to a value which gives an estimate electron density a
     factor of two times the estimated ion density. This is no longer
     used in L2 production.
     10) the estimated potential is saved in a tplot variable called
     'th(probe)_est_scpot' which can be interpolated to the time arrays
     for the different ESA modes.
     11) If the keyword time_smooth_dt is set, then the potential is
     smoothed using that time range. The default for ESA L2 production is
     120.0 seconds.
    HISTORY:
     3-mar-2016, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2025-08-04 15:41:41 -0700 (Mon, 04 Aug 2025) $
     $LastChangedRevision: 33532 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot2.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot2.pro)

## THM_ESA_QUALITY_FLAGS[1]

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

    Procedure:
      thm_esa_quality_flags

    Description:
      makes a bitpacked tplot variable containing quality flags for ESA
      bit0 = pre-efi boom deployment (using zeroed spacecraft potential)
      bit1 = counter overflow flag
      bit2 = solar wind mode flag(disabled)
      bit3 = flow flag, flow less than threshold is flagged
      bit4 = earth shadow
      bit5 = lunar shadow
      bit6 = manuever flag

      Set timespan by calling timespan outside of this routine.(e.g. time/duration is not an argument)

    Keywords:
      probe(required): probe letter ('a','b','c','d','e')
      datatype(required): type string  ('peef','peib', etc...)
      noload(optional): set this if calling from thm_l2gen_esa
      flow_threshold(optional): flow threshold for flow flag(default = 1.0, units undocumented)

     $LastChangedBy: jimm $
     $LastChangedDate: 2018-03-12 14:57:15 -0700 (Mon, 12 Mar 2018) $
     $LastChangedRevision: 24875 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_quality_flags.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_quality_flags.pro)

## THM_ESA_QUALITY_FLAGS[2]

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

    HELPER FUNCTION (main function below)
     Returns the start and end indices of intervals where a condition
     applies

(See projects/themis/spacecraft/particles/ESA/thm_esa_quality_flags.pro)

## THM_ESA_TEST_SPEC3D2

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

    NAME:
     thm_esa_test_spec3d2
    PURPOSE:
     Wrapper for spec3d2, plots PEEF, PEER, PEEB data; the user clicks on
     a time, and spec3d2 estimates the sc potential for each mode, and
     plots the distribution with the potential overplotted. A black line
     for the measured potential, and a red line for the
     estimated potential
    INPUT:
     date = a date, e.g., '2008-01-05'
     probe = a probe, e.g., 'c'
    OUTPUT:
     plots of the 3d distribution for each mode, with SC_POT plotted on
     the graph.
     init = if set, read in a new set of data
     random_dp = if set, the input date and probe are randomized, note
                 that this keyword is unused if init is not set.
    HISTORY:
     31-may-2015, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2015-07-24 15:57:59 -0700 (Fri, 24 Jul 2015) $
     $LastChangedRevision: 18252 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_esa_test_spec3d2.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_test_spec3d2.pro)

## THM_LOAD_L2_ESADIST

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

    NAME:
     thm_load_l2_esadist
    PURPOSE:
     Loads THEMIS ESA L2 data for a given file(s), or time_range
    CALLING SEQUENCE:
     thm_load_l2_esadist, trange=trange, datatype=datatype
    INPUT:
     All via keyword, if none are set, then the output of timerange() is
     used for the time range, which may prompt for a time interval
    KEYWORDS:
     probe = ['a', 'b', 'c', 'd', 'e'] is the default
     datatype = ['peif', 'peir', 'peib', 'peef', 'peer', 'peeb'] is the default
     trange = read in the data from this time range, note that if both
              files and time range are set, files, and orbits take precedence in
              finding files.
     no_time_clip = if set do not clip the data to the time range. The
                    trange is only used for file selection. Note that
                    setting no_time_clip will always generate a reload of
                    data
    OUTPUT:
     No variables, data are loaded into common blocks
    HISTORY:
     7-nov-2022, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2023-09-19 14:54:55 -0700 (Tue, 19 Sep 2023) $
     $LastChangedRevision: 32106 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_load_l2_esadist.pro $

(See projects/themis/spacecraft/particles/ESA/thm_load_l2_esadist.pro)

## THM_LOAD_PXXM_POT4ESA

[Previous Routine] [List of Routines]

    NAME:
     thm_load_pxxm_pot4esa
    PURPOSE:
     loads the pxxm_pot variable for ESA processing, performs a time
     offset, and also loads the efs_Potl variable fro FIT files, if it
     exists.
    CALLING SEQUENCE:
     thm_load_esa_pxx_pot4esa, probe=probe, trange=trange,suffix=suffix
    INPUT;
     All via keyword
    OUTPUT:
     For each probe, a tplot variable 'thx_pxxm_pot', which is the SC
     potential that comes directly from the MOM L1 files, a variable,
     'thm_pxxm_pot_0', that includes a time correction,
    KEYWORDS:
     probe - ['a','b','c','d','e']
     trange -  the time range, otherwise just use whatever's there
    HISTORY:
     11-May-2010, jmm, jimm@ssl.berkeley.edu
    $LastChangedBy: aaflores $
    $LastChangedDate: 2012-01-10 10:56:14 -0800 (Tue, 10 Jan 2012) $
    $LastChangedRevision: 9526 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/ESA/thm_load_pxxm_pot4esa.pro $

(See projects/themis/spacecraft/particles/ESA/thm_load_pxxm_pot4esa.pro)