CCSDYDNM000200NSSD0021SMRK0001 TEXT_DESCRIBING_THE_ANALYSIS_SOFTWARE.TXT W.K. Peterson July, 1989 Documentation on the general purpose EICS analysis program to be provided to read the SATF and return geophysical parameters. A program and associated documentation that returns velocity space densities, fluxes, or count rates for the various ion species sampled, running under the VMS operating system, appears in the top level directory [EICS]EICS.EXE This program is routinely used in EICS data analysis. A scenario on this is as follows : SCENARIO FOR PROCESSING EICS DATA A typical problem for a user of the EICS Data is to obtain selected particle fluxes for a specific desired time period. Before any other parameters are considered, data for the desired times must be located on the optical disks. To do this : 1) Locate the desired time period in the EICSDATA.LIS file. Its format is described in the file TEXT_DESCSRIBING_THE_INDEX_FILE.TXT. The EICSDATA.LIS file is ordered in year-day order. The first two fields contain a five-place integer followed by a letter. The first two digits of the first field are the year and the next three are the day of the year ( This number appears on many desk calendars. ). These five digits are followed by a letter. The file name for a data-set consists of the letter C as a prefix followed by the above fields (i.e. a five-digit date followed by an alphabetic character). The number of records in this file follows in the third field. The start time is a 4-digit integer in the fourth field. The stop time is in the fifth field. BE SURE TO USE THE EICSDATA.LIS FILE ON THE MOST RECENTLY CREATED DISC VOLUME IN YOUR POSSESSION. AN OLDER INDEX WILL NOT INCLUDE DATA PROCESSED AFTER ITS CREATION - DATA IS NOT PROCESSED IN CHRONOLOGICAL ORDER. Refer to the text file on the disk TEXT_DESCRIBING_THE_INDEX_FILE.TXT for help. The tape number this data was on will be in the eleventh field. All tape numbers can be expressed as 1 to 3 digits preceded by a T. If desired, start and stop times are available in milliseconds of the day, 8-place integers in fields six and seven, respectively. Data quality flags are also present in the eighth, ninth, and tenth fields. 2) To locate the data for the "Tape Number" on the appropriate optical disk file, use OPTICAL_VOLUME_INDEX.LIS. AGAIN, BE SURE TO USE THE VERSION OF OPTICAL_VOLUME_INDEX.LIS on the most recent optical volume in your possession. The tape numbers are in the first field of TABLE2. Note that the letter T which appears as a prefix to all tape numbers on EICSDATA.LIS is omitted from the tape number as found in TABLE2. The desired optical disk volume is the second (20-character) field. See the file Text_Describing_the_Optical_Volume_Index.TXT for more details on use of the index to locate data. 3) We now mount each optical disk volume that contains data we want. We know the file name from the EICSDATA.LIS file as described above (#1). The file is located in a sub-directory with a name derived from the tape number. For example the file C81287M.DAT on tape 11 is found the optical volume DEA6_0001A in the sub-directory [EICS.T00011]. These data files are referred to as SATF files. They contain many 8-second blocks of telemetry, orbit/attitude data, and data quality flags. Remember that the sub-directory name is the same as the tape number and that the T prefix is included in this name. 4) Run the EICS.EXE file found on each disk. Give it the full path name for each file determined above for the data you want processed. You will be prompted to enter start and stop times, a mode, spins/interval or cycles/interval, energy bins, angular resolution, filter, mass setting, etc. These options are described below. 5) If EICS.EXE does not execute, contact NSSDC for the EICS software source code and linking instructions. However NSSDC does not guarantee to maintain the software against changes in operating environments. 6) The output of the EICS.EXE program is explained by the file ANNOTATED_OUTPUT_LISTING.TXT which is present on each volume. An example of the inputs to this program to produce a listing of the velocity_space densities and standard deviations in 8 equally spaced pitch angle ranges for all ion species sampled between 0605 and 0610 on January 6, 1984 is shown below. +----------------------------------------------------------------------------- -+ | | | 1. Filename OPTICAL_DISK_NAME:[EICS.T00146]C84006B.DAT | | 9. 8 angular bins | | 2. Start: 84006:06:05:00 = 21900 | | 10. Select normal pitch angle | | 3. Stop: 84006:06:10:00 = 22400 | | 11. Don't use filter | | 4. Single time interval | | 12. Use first M/Q values found | | 5. no specific mode selected | | | | | | 6. Use MD2 13. Don't write any plot information | | | | | | 7. No ED specified 14. Print now | | | | 8. Accumulate 15 STD ESA and 15. Final output: Velocity Space | | 16 STD RPA channels (no ED) | +----------------------------------------------------------------------------- -+ Enter -1 or to quit EICS. Enter menu # to change or 0 to accumulate with the above parameters: The plot file referred to in item 13 above is an ASCII file that is readable by code created at Lockheed using Version 5.0 of high level graphics language DI-3000 to create line plots. While the basic fortran calls to DI-3000 routines have remained constant, successive versions have required development of new procedures to 'LINK' EICS fortran and pascal code with DI-3000 code. We will therefore not transfer graphics code to the NSSDC because of the indeterminate labor costs associated with establishing and supporting interfaces to high level graphics languages in unknown and changing environments. Below the various options in the above menu are explained and an annotated listing of the output is given. Narrative description of options (questions) associated with the EICS.EXE program. >>To run the code from the optical device use the commands $run optical_device:[eics]EICS.EXE Interactive? (Y/N): >>answer y and you get the following y Error 29 on opening the file in subroutine opencfile. >> The screen is cleared and the following display appears. +----------------------------------------------------------------------------- -+ | | | 1. Filename Your_current_default_disk_and_directory:EICSDATA.DAT | | 9. 8 angular bins | | 2. Start: 00000:00:00:00 = 00000 | | 10. Select normal pitch angle | | 3. Stop: 00000:00:00:00 = 00000 | | 11. Don't use filter | | 4. Single time interval | | 12. Use first M/Q values found | | 5. no specific mode selected | | | | | | 6. Use MD2 13. Don't write any plot information | | | | 7. No ED specified 14. Print now | | | | 8. Accumulate 15 STD ESA and 15. Final output: Flux | | 16 STD RPA channels (no ED) | +----------------------------------------------------------------------------- -+ Enter -1 or to quit EICS. Enter menu # to change or 0 to accumulate with the above parameters: >>You now must enter a VALID FILE NAME: ENTER 1 followed by a CR >>which returns the prompt in the bottom scrolling area of screen: Enter file name: >>If you enter an invalid file name (such as file_not_there.dat) >>you get the error: Error 29 on opening the file in subroutine opencfile. Error - file file_not_there.dat not found >> when a valid file name such as QSA0:[EICS.T00317]C85053A.DAT >>is entered the file and its start time and stop times are entered on >>the full page display as illustrated below. (Note QSA0: is the optical >>disk reader on some, but not all systems.) +----------------------------------------------------------------------------- -+ | | | 1. Filename QSA0:[EICS.T00317]C85053A.DAT | | 9. 8 angular bins | | 2. Start: 85053:15:03:43.862 = 54254 | | 10. Select normal pitch angle | | 3. Stop: 85053:16:31:47.819 = 59508 | | etc | | | +----------------------------------------------------------------------------- -| Enter -1 or to quit EICS. Enter menu # to change or 0 to accumulate with the above parameters: >>At this point you can enter a 0 and data for the data or the 15:03:43.862 >>to 16:31:47 on day 53 (February 22) of 1985 will be accumulated and written >>to file FOR108.DAT in your current working directory. The structure of >>the output file is discussed below. >> If the you want to accumulate data for a shorter interval, use fewer >>angular bins, etc. you can select menu #s 2 to 15. >> >> >>OPTIONS 2 and 3 change the time interval and provide for a series of regular >>accumulation intervals. The basic prompt is: Enter starting date or -1 to quit [85053]: >>-1 will cause the program to terminate. >>a return will set the date to the value in brackets 85053 in this case. >>You are next prompted: Enter time in seconds, hh:mm:ss, hh:mm or "MS=" : >>valid responses to this are for example: >> 13:10:00 >> 13:10 >> 14: >> 48123 >> MS=49143123 >>which will start (or end) the accumulation at the following times given in >>seconds of the day 47400, 47400, 50400, 48123, and 49143.123 >>Note that the program starts or stops the accumulation at intervals of 1/16 >>of the basic 8 second telemetry block or 0.5 seconds. >> >>OPTION 4 determines if a single of multiple accumulations are to be >>made. Selecting Menu item # 4 returns the prompt: Measure time in [S]pins per interval, instrument [C]ycles, or use a single [T]ime interval? (SCT) [T]: >> Selecting S gives the following prompt: Enter # of spins/interval: >> Selecting C gives the prompt: Enter # of cycles/interval: >> >> Each spin period is six (6) seconds. EICS modes have cycle times of >> 4, 16, 20, and 32 spin periods. You can select any number greater >>than 1 and less than or equal to 999. The program will accumulate >>data for the specified number of EICS mode cycles or satellite spin >>periods, provide the output specified by options 13,14, and 15 for >>successive intervals starting and stoping at the times specified by >>options 2 and 3. >> >>OPTION 5 is used to select specific EICS mode types. For normal data >>processing the default is appropriate. >>Selecting option 5 returns the following output: Mode type codes: -1: no specific mode selected 0: all modes 1: run mode 2: run drum modes 3: LOSC mode 4: LODM mode Enter mode type [-1]: >> >>OPTION 6 selects one of two detector threshold settings. For normal >>data processing the default is appropriate. Selecting >>option 6 returns: Enter 1 or 2 for MD1 or MD2 [2]: >> >>OPTION 7 selects one of the two non-mass resolving 'energy detectors', >>only one of which is operated in each EICS mode. For normal data >>processing the default is appropriate. Selecting >>option 7 gives the following prompt. Enter 1 for ED1, 2 for ED2, 0 or for unspecified ED: >> >>Option 8 selects one of three possible sets of energy bins. In >>some non-standard modes the EICS instrument returns data from 64 >>discrete energy ranges. For normal data the default <15 STD ESA ..etc> >>is appropriate. Selecting Selecting option 8 returns the following >>prompt. Accumulation codes: E: 32 ESA energy channels R: 32 RPA energy channels S: 15 STD ESA and 16 STD RPA channels Enter accumulation code [S]: >> >>Note selecting options E or R will change the format of the output >>listing (Option 14). >> >> >>OPTION 9 selects one of 64 possible angular resolutions. The default >>is to 'bin' the data into eight (8) angular bins. Because EICS >>counting rates are at times low it is sometimes useful to select >>less than 8 angular bins. Selecting option 9 gives the following >>prompt: Enter number of angular bins (1-64) [8]: >>The response to this prompt is self evident. All of the angular bins >>are uniformly spaced. >> >>Option 10 is used to select the 'type' of angular sorting to be done. >>The default