This page was created by the IDL library routine mk_html_help2.

Last modified: Thu May 29 18:17:56 2025.


Directory Listing of Routines


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_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
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: 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_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 and PEIR
 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
 $LastChangedBy: jimm $
 $LastChangedDate: 2023-02-06 15:08:13 -0800 (Mon, 06 Feb 2023) $
 $LastChangedRevision: 31478 $
 $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_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_dens2scpot 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.
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.
 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-03-11 14:41:23 -0700 (Tue, 11 Mar 2025) $
 $LastChangedRevision: 33166 $
 $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)