
This File Is: HOW_TO_USE_REDUCE_SATM.TXT

Subj: How to use REDUCE_SATM IDL code to process Dynamics Explorer LAPI and 
	HAPI files

REDUCE_SATM will decommutate HAPI/LAPI telemetry from the Stand Alone 
Telemetry (SATM) files, separate the data into steps and sweeps, and convert 
the data to geophysical units. 

Description of REDUCE_SATM:

REDUCE_SATM
- Calls PROCESS_SATM
- Calls CALC_FLUX
- Creates IDL save set

PROCESS_SATM   (Called from REDUCE_SATM)
- Calls READ_SATM
- Breaks SATM data into sweeps and steps 
- Separates detectors into ions and electrons
- Puts information about data into HLAPI structure
- Uses HLAPI_INTERP to interpolate OA data and magnetic field data
- Puts OA and magnetic field data into EA structure
- Calls CALC_PA_HAPI or CALC_PA_LAPI
- Calls SORT_SENS_HAPI or SORT_SENS_LAPI

READ_SATM      (Called from PROCESS_SATM)
- Pulls out the part of the SATM file that corresponds to the requested time

CALC_PA_HAPI or _LAPI  (Called from PROCESS_SATM)
- Calculates pitch angles

SORT_SENS_HAPI or _LAPI  (Called from PROCESS_SATM)
- Sorts sensors in order of geometrical location
- Puts data into EA structure

CALC_FLUX  (Called from REDUCE_SATM)
- Calculates actual counts from TM counts
- Calculates requested flux 

Some additional files have been included as sample display routines.

HOWTO.PRO gives a way to call multiple IDL savesets for some processing task.

CURRENTSR.PRO computes currents from the LAPI data. A version that also 
computes HAPI currents may be added.

LAPISPEC4.PRO produces spectrograms of HAPI and LAPI data. It call 
goodcolor.xdr (a binary IDL saveset) to load a selected color table. This call
can be replaced with "loadct,13" or other color table.

DF2.PRO makes phase space plots of distribution function data and calls 
contour_even.pro to get even X and Y scales.

BATCH.COM is a VMS batch file to show how reduce_satm may be called in batch 
mode. A similar scheme may be used in Unix.


Instructions:

1.  Look at THIS_SIDE.DATA_FILE_LIST or ALL_4(3)_SIDES.DATA_FILE_LIST to find 
    the name of the SATM file that contains the time period that you want.

2.  Copy SATM file to your local directory

3.  Copy the hlapi_software.tar-gz (a VMS Backup file is also available) to
    your local directory (yourdir) and uncompress and untar 
    ( zcat hlapi_software.tar-gz | tar xvf - ) to get the individual *.pro
    files. 

4.  Run idl.

5.  To call the routines from any directory, add the location of the *.pro 
    files to your IDL search path with:
     !path='yourdir,'+!path ; for VMS
     !path='yourdir:'+!path ; for Unix

    ** This can be set up permanently, by placing this command in your account's
    IDL startup file.  Refer to the IDL manual to the pages listed in
    the index for 'IDL_STARTUP' for instructions on how to do this.
    
6.  Type: 
    reduce_satm,"satmfilename",yrday,sh,sm,ss,eh,em,es,flux_option=n
    where
      satmfilename   =    name of SATM file       (ex. L821040921C.satm)
      yrday          =    date of time requested  (ex. 82104)
      sh             =    starting hour requested
      sm             =    starting minute requested
      ss             =    starting second requested
      eh             =    ending hour requested
      em             =    ending minute requested
      es             =    ending second requested
      n              =    1 for raw counts
                          2 for number flux (# / (cm^2 sr eV sec))
                          3 for energy flux (ergs / (cm^2 sr eV sec))
                          4 for distribution function (s^3 / m^6)

                           **    OR    **

    just type reduce_satm  and it will prompt you for the parameters.

7.  If you want to process the whole file just add ,/whole_file 
    (i.e. reduce_satm,/whole_file or 
	  reduce_satm,"satmfilename",flux_option=n,/whole_file).
    
8.  If you want to dump the data in major frames add ,/debug .

9.  Data is saved in an IDL saveset in XDR format.  The file can be restored 
    later.  It can also be transferred to a UNIX system and read into the UNIX 
    version of IDL. The SATM files may be able to be processed directly on Unix 
    systems, but this capability has not been well tested.

The IDL save set contains the following: 

Array of EA STRUCTUREs for each sweep:
This structure contains data for the HAPI/LAPI electrostatic analyzers.  

EA.TIME:
  lonarr EA(nsweeps).time
  units: miliseconds
  This will contain the time of the beginning of the sweep in miliseconds, if 
  the data crosses over to another day, 86400,000 ms (1 day) will be added.
EA.ILAT
  fltarr EA(nsweeps).ilat
  units: degrees
  The invariant latitude at the start of each sweep.
EA.MLT
  fltarr EA(nsweeps).mlt
  units: hours
  The magnetic local time at the start of each sweep.
EA.ALT
  fltarr EA(nsweeps).alt 
  units: kilometers
  The altitude of the spacecraft at the start of each sweep.
EA.LAT
  fltarr EA(nsweeps).lat
  units: degrees
  The spacecraft latitude at the start of each sweep.
EA.LON
  fltarr EA(nsweeps).lon
  units: degrees
  The spacecraft longitude at the start of each sweep.
EA.LST
  fltarr EA(nsweeps).lst
  units: hours
  The local time at the start of each sweep.
EA.LSHELL
  fltarr EA(nsweeps).gmlat
  units: Earth radii
EA.GEI_SPEED
  fltarr EA(nsweeps).gei_speed
  units: km/sec
  The speed (velocity magnitude) of the spacecraft in GEI coordinates at the 
  start of each sweep.
EA.SZA
  fltarr EA(nsweeps).sza
  units: degrees
  The solar zenith angle at the start of each sweep.
EA.DARK_LIGHT
  bytarr EA(nsweeps).dark_light
  units: n/a
  This is the day/night indicator flag at the start of each sweep.  It is set 
  to 1 (true) in daylight, and 0 (false) at night.
EA.SENSORS_ELEC
  bytarr EA(nsweeps).sensors_elec(nsensors_elec)
  units: n/a
  This contains the sensor IDs for each electron detector in each sweep.  
  This usually doesn't change with the sweeps, but sometimes it does. 
  BE CAREFUL!  See FORMAT.SFD to explain the sensor ID numbers.
EA.PA_ELEC
  fltarr EA(nsweeps).pa_elec(nsensors_elec) for LAPI
  fltarr EA(nsweeps).pa_elec(nsensors_elec,nsteps) for HAPI  
  units: degrees
  The pitch angle for each electron sensor for each sweep.
EA.COUNTS_ELEC
  bytarr EA(nsweeps).counts_elec(nsensors_elec, nsteps)
  units: commutated (telemetered) counts
  This contains the counts of each electron detector for each energy level for 
  each sweep.  The detector energy level can be found in the array:  ENERGY.
EA.SENSORS_IONS
  bytarr EA(nsweeps).sensors_ions(nsensors_ions)
  units: n/a
  This contains the sensor IDs for each ion detector in each sweep.
  This usually doesn't change with the sweeps, but sometimes it does. 
  BE CAREFUL!  See FORMAT.SFD to explain the sensor ID numbers.
EA.PA_IONS
  fltarr EA(nsweeps).pa_ions(nsensors_ions) for LAPI
  fltarr EA(nsweeps).pa_ions(nsensors_elec,nsteps) for HAPI  
  units: degrees
  The pitch angle for each ion sensor for each sweep.
EA.COUNTS_IONS
  bytarr EA(nsweeps).counts_ions(nsensors_ions, nsteps)
  units: commutated (telemetered) counts
  This contains the counts of each ion detector for each energy level for 
  each sweep.  The detector energy level can be found in the array:  ENERGY.


HLAPI Structure:
This structure contains data which is valid for the whole time range (does not 
vary with sweep).

HLAPI.YRDAY
  long
HLAPI.SATID
  string
  L  - LAPI
  H  - HAPI
HLAPI.SATM_FILE
  string
  SATM file name
HLAPI.VERSION
  string
  version of PROCESS_SATM 
HLAPI.NSENSORS
  int 
  number of sensors
HLAPI.ORBIT
  float
  orbit number
HLAPI.NSWEEPS
  int
  number of sweeps
HLAPI.NSTEPS
  int
  number of energy steps per sweep
HLAPI.STEPS_PER_SECOND
  int
HLAPI.NSENSORS_ELEC
  int
  number of electron sensors
HLAPI.NSENSORS_IONS
  int
  number of ion sensors
HLAPI.PPS(nsteps)
  bytarr
  see FORMAT.SFD
for LAPI:  

 HLAPI.START_PPS1  \
 HLAPI.STOP_PPS1     \
 HLAPI.SKIP_PPS1       \
 HLAPI.STEP_PPS1         \
 HLAPI.START_PPS2          \
 HLAPI.STOP_PPS2             \
 HLAPI.SKIP_PPS2               \                        
 HLAPI.STEP_PPS2                  see FORMAT.SFD        
                               /
for HAPI:                    /
                           /
 HLAPI.START_PPS1        / 
 HLAPI.STOP_PPS1       /
 HLAPI.SKIP_PPS1     /
 HLAPI.STEP_PPS1   /


Array of GM Structures for each sweep  (for LAPI only):
This stucture contains the Geiger-Muller Tube data.

GM.TIME
  lonarr   GM(num).time
  units: miliseconds
GM.GM_0
  fltarr   GM(num_GM).GM_0
  telemetered Geiger-Muller counts for 0 degrees 
GM.GM_90   
  fltarr   GM(num_GM).GM_90 
  telemetered Geiger-Muller counts for 90 degrees 

These additional variables in the IDL save file contain flux values.

FLUX_OPTION:
  int
  1, 2, 3, or 4 (corresponds to type of flux)
FLUX_TYPE:
  string
  type of flux (raw counts, number flux, energy flux, or distribution function)
FLUX_ELEC:
  fltarr    flux_elec(nsensors, nsteps, nsweeps)
  electron flux
FLUX_IONS:
  fltarr    flux_ions(nsensors, nsteps, nsweeps)
  ion flux
FLUXONE_ELEC:
  fltarr    fluxOne_elec(0 or 1,nsweeps)
  baseline for electron flux at count=1
FLUXONE_IONS:
  fltarr    fluxOne_ions(0 or 1,nsweeps)
  baseline for ion flux
GEIGER_0 (LAPI) : 
  fltarr    geiger_0(num_GM)
  Geiger-Muller data for 0 degrees
GEIGER_90 (LAPI) :
  fltarr    geiger_90(num_GM)
  Geiger-Muller data for 90 degrees
ENERGY
  fltarr    energy(nsteps)
