Document title: HOW_TO_USE_REDUCE_SATM.TXT for NDADS DE LAPI datatype Project: DE NDADS Datatype: LAPI Super-EID: DOCUMENT There may be other documents also identified by this super-EID. NDADS filename: LAPI_HOW_TO_USE_REDUCE_SATM.TXT TRF entry B46549.txt in NSSDC's controlled digital document library. Feb. 1998. Document text follows: ---------------------- 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: radians (was marked as degrees, 2020Feb12) 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 FLUXZERO_ELEC: fltarr fluxzero_elec(0 or 1,nsweeps) baseline for electron flux FLUXZERO_IONS: fltarr fluxzero_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)