TIDE Level-Zero Processing and Display Software ************************************* * * * Preliminary Documentation * * * ************************************* Peggy Sloan, CSC written in November 1994 updated in May 1995 Table of Content I. Introduction II. Software Summary III. TIDE level-zero processing software: tide_lz, tide_mf, cal_mf, cal_lz output file formats data structures IV. TIDE ion count rate processing software, tide_masses V. TIDE level-zero display software mass spectrograms: run_spect chromograms: cg_polar, cg_rpa, cg_spin VI. TIDE calibration mode plot routines realtime displays: run_tide and run_sing post-processing: plot_sing, plot_mass, plot_de contour plots: con_mass, con_sing, con3d_mass, con_sing VII. Utility software byte_dump lz_dump housekeeping I. Introduction The TIDE level-zero processing and display software is used to read, process, and plot data contained in Thermal Ion Dynamic Experiment (TIDE) telemetry files. The files can be either GSFC level-zero formats or GSE major frame formats. The files can have either spin header format. The original get_spins software can only read and process GSE major frame formats with the old spin header format. II. Software Summary The current versions of all the software executables are stored on cyclops in /data.local/appleshare/TIDE.test/flight. The C executables used to run the TIDE level-zero processing software are: cal_lz processes level-zero data containing the old spin header format, which includes only files created at GSFC during the January to April 1995 Thermal Vacuum testing. cal_mf processes GSE-generated major frame data containing the old spin header format including all telemetry generated at MSFC and SWRI prior to Fall 1993 plus all GSE telemetry generated during the initial satellite integration, Fall 1993 to April 1995. Note: These data can also be processed using the original 'get_spins' software. tide_mf processes GSE-generated major frame data created at SWRI and MSFC in 1994 and 1995 plus final integration and test major frame data. tide_lz processes all MSFC-generated level-zero simulated data sets plus all pre-flight and flight GSFCgenerated level-zero data created after May 1995. The PV~WAVE (IDL) command files used to run the TIDE plot routines are: cg_polar creates TIDE chromograms based on polar angle cg_rpa creates TIDE chromograms based on RPA voltage cg_spin creates TIDE chromograms based on spin angle run_spect creates TIDE spectrograms run_sing creates realtime calibration mode singles and direct-event line plots run_tide creates realtime calibration mode mass spectrograms and singles and direct-event line plots plot_de creates direct_event line plots plot_mass creates calibration mode mass spectrograms plot_sing creates calibration mode singles events line plots and direct-event line plots con_sing contours LEIF lab calibration mode singles event tilt or rotate data con3d_sing contours LEIF lab calibration mode singles event tilt and rotate data con_mass contours LEIF lab calibration mode ion mass tilt or rotate data con3d_mass contours LEIF lab calibration mode ion mass tilt and rotate data Files containing the software source code are stored in subdirectories of /data.local/appleshare/TIDE.test/flight. The files containing the source code for the TIDE level-zero processing software are: Makefile The makefile used to create 'tide_lz', the program used to read and process TIDE telemetry formatted as level-zero records. The software is created by simply typing 'make' Mtide_mf The makefile used to create 'tide_mf', the program used to read and process TIDE telemetry formatted as PCGSE major frame data records containing the flight spin header format. The command to use this file is 'make -f Mtide_mf'. Mcal_mf The makefile used to create 'cal_mf', the program used to read and process TIDE telemetry formatted as PCGSE major frame data records containing the original spin header format. The command to use this file is 'make -f Mcal_mf'. Mcal_lz The makefile used to create 'cal_lz', the program used to read and process TIDE telemetry formatted as level-zero records, containing the original spin header format. The command to use this file is 'make -f Mcal_lz'. Mmasses The makefile used to create 'tide_masses', the program used to further process ion mass count rates. The input is created by option 1, suboption 1 of tide_lz, tide_mf, cal_mf, or cal_lz. The command to build tide_masses is 'make -f Mmasses'. tide_lz_main.c The main C function used to start processing TIDE telemetry data get_dp.c C functions used by both tide_lz and tide_mf to process specific data product data get_lz.c C functions used by tide_lz to read and process level- zero data records get_mf.c C functions used by tide_mf to read and process major frame data records get_spins.c C functions used to locate and process spin data ricedcmp.c C functions, written at SWRI, used to decompress Rice compressed ion count rate data products cal_mf_main.c The main C function used to start processing TIDE telemetry data containing the original format cal_mf_dp.c C functions used by cal_mf to process specific data product data cal_get_lz.c C functions used by cal_lz to read and process level- zero data records cal_get_mf.c C functions used by cal_mf to read and process major frame data records cal_mf_spins.c C functions used to locate and process calibration mode spin data cal_mf_rice.c C functions, written at SWRI, used to decompress Rice compressed ion count rate data products tide_masses.c The main C function used to further process TIDE ion count rates. mass_chromo.c C functions called by tide_masses to create the input for both the generalized chromogram software and for the TIDE- specific versions of the chromogram software mass_spect.c C functions called by tide_masses to further process ion mass count rates and to create the input for the TIDE spectrogram software C header files containing global variable and function definitions used by tide_lz and tide_mf: tide_lz_def.h sets up frequently used parameter values tide_lz_func.h sets up all C functions as external tide_lz_glob.h defines global variables and arrays tide_lz_parm.h sets up global variables and arrays as external tide_lz_stru.h defines the global data structures C header files containing global variable and function definitions used by cal_mf: cal_mf_def.h sets up frequently used parameter values cal_mf_func.h sets up all C functions as external cal_mf_glob.h defines global variables and arrays cal_mf_parm.h sets up global variables and arrays as external cal_mf_stru.h defines the global data structures C header files containing global variable and function definitions used by tide_masses: tide_mss_glob.h defines global variables and arrays tide_mss_xtrn.h defines global variables and arrays as external Files contain the PV~WAVE (IDL) source code for the TIDE spectrogram and chromogram plot routines are: tide_spect.pro main TIDE spectrogram plot procedure label_spect.pro procedures called to set up and label TIDE spectrograms plot_spect.pro procedures called to plot TIDE spectrograms tide_cg_polar.pro main polar angle based TIDE chromogram plot procedure tide_cg_rpa.pro main RPA voltage based TIDE chromogram plot procedure tide_cg_spin.pro main spin angle based TIDE chromogram plot procedure cg_util.pro procedures called by all three chromogram routines polar_cg_util.pro polar angle specific plot procedures rpa_cg_util.pro RPA voltage specific plot procedures spin_cg_util.pro spin angle specific plot procedures Files contain the PV~WAVE (IDL) source code for TIDE calibration mode plot routines are: con_mass_3d.pro main routine used to contour LEIF lab tilt/rotate mass data con_sing_3d.pro main routine used to contour LEIF lab tilt/rotate singles data contour_3d.pro utility routine used by both con_mass_3d.pro and con_sing_3d.pro contour_mass.pro contours ion mass LEIF lab tilt or rotate mass data contour_sing.pro contours ion mass LEIF lab tilt or rotate singles data direct_event.pro main routine used to create direct-event line plots label_plots.pro plot labeling procedures called by the calibration mode plot routines load_color.pro routine used to load calibration mode mass spectrogram color table mass_spect.pro main routine used to create mass spectorgram plots plot_data.pro procedures called by the calibration mode plot routines singles.pro main routine used to create singles event line plots singles_de.pro main routine used to create realtime singles and direct-event line plots tide_plot.pro main routine used to create realtime mass spectrograms and singles and direct-event line plots III. TIDE level-zero processing software: tide_lz, tide_mf, cal_mf, and cal_lz There are four versions of the level-zero processing software. tide_lz reads and processes files containing the flight-formatted level-zero data records. tide_mf reads and processes telemetry files created by the PCGSE that contain major frame data records that include major frame headers and the flight version of the spin header. cal_mf reads and processes telemetry files created by the PCGSE that contain major frame records with the original spin header format. cal_lz reads and processes level-zero data containing the original spin header format. NOTE: PCGSE telemetry created and stored on tide3 prior to November 1993 and data generated and stored on tide2 prior to instrument refurb can be be processed using the original TIDE calibration software get_spins, post_spins, and tide_plot. tide_lz, tide_mf, cal_mf, and cal_lz are executed in the exact same way and have the same user prompts. They are executable files stored on cyclops in: /data.local/appleshare/TIDE.test/flight The software expects to find the telemetry files in a directory pointed to by the environmental variable SUN_PATH. To set up this variable and to make referencing the software easier, add or change the following lines in your .login file: setenv SUN_PATH /data.local/appleshare/TIDE.test/flight/lz_data setenv tide /data.local/appleshare/TIDE.test/flight Each time you login, $tide becomes a pointer to the location of the software and $SUN_PATH becomes a pointer to the location of the telemetry. If the telemetry is not in the lz_data subdirectory, SUN_PATH can be reset any time by simply typing the setenv command with the new directory. SUN_PATH must exist in order for the software to run. The easiest way to describe the software is to discuss each user prompt as it is used. To start execution of the software type: $tide/tide_lz or $tide/tide_mf or $tide/cal_mf or $tide/cal_lz The software checks for the value of SUN_PATH. If SUN_PATH does not exist, the software stops after typing: The environmental variable SUN_PATH must be set to the path of the directory containing the telemetry files before running tide_lz or get_spins. If SUN_PATH exists, the software types: The program expects to find the level-zero data files in: If the files are not in this directory, you can stop execution with the next prompt, which determines the telemetry file handling option: opt description --- ---------------------------------------- 0 stop 1 process single level-zero data file 2 process multiple level-zero data files 3 process realtime lab data file handling option => Program execution stops, if 0 is typed. If option 1 is selected, the user is asked for the name of the file to be processed: level-zero filename (no path) => If option 2 is selected, the names of all the files to be processed need to be in a file called tide_lz.lst in the current working directory, one name per line, no path. If tide_lz.lst does not exist, execution stops with this message: Unable to open tide_lz.lst. Option 3 is selected when the software is run realtime during lab instrument testing. It runs like the get_spins realtime option. It expects to find the telemetry filenames in 'filelist' in SUN_PATH. If filelist does not exist, execution stops with this warning: Unable to open filelist. If at anytime during program execution, a new telemetry file cannot be opened, execution stops with: Unable to open Whenever a new telemetry file is opened, the user is informed with: Processing of started In order to save time in data processing of large telemetry files, the processing can start and/or stop at user-specified times. Flight times are in month-day-year (2 digits each) and a 24-hour hour:minute:second clock. The times are always universal time (UT). The start/stop time prompts are: Do you want to specify the start time? (y/n) start time (mn-dd-yr hh:mm:ss) => Do you want to specify the stop time? (y/n) stop time (mn-dd-yr hh:mm:ss) => If the user-specified start time is not found, execution stops with: Start time not found. Before any processing starts, the software determines what type of processing is to be done and what output files are to be created. The user can select more than one processing option. The software keeps track of which options have been selected by setting bits in the option variables. The user enters a 1 for bit options he wants and 0 for options he does not want. Run- time instructions are: Enter a 1 if you want the data, a 0 if you don't. Enter the 1's and 0's on the prompt line, no blanks, in the order the processing options are listed. bit processing option description --- -------------------------------------------------- 0 stop 1 save science mode ion count rates 2 save housekeeping bytes 3 save instrument parameters 4 save spin header data 5 save calibration mode data 6 save sector zero direct event data 7 save dump mode data 8 save data product hex dump process option (0 or 1 for each bit) ==> Processing option selection examples: user input options selected -------- --------------------------------------------------------------- 0 program stops execution 1 science mode ion counts saved 01 housekeeping bytes saved 1011 ion counts, instrument housekeeping, and spin header data saved 00001 calibration mode singles and mass counts saved 11111111 all options selected -------- --------------------------------------------------------------- Most of these options have sub-options which further define the data saved. In most cases, multiple sub-options can also be selected. Sub-option selection is done the same way, with the user selecting (1) or not selecting (0) options. If option 0 is selected, the program stops after typing: No processing option selected. Most of the data files created by the software have the same filename as the first telemetry file processed but with a new file extension. The extension indicates the type of data the file contains. All output files are created in the current working directory. One output file is always created, regardless of the option selected. .err contains information and errors pertaining to the processing. The user should look at the file after program execution to find out if and where processing errors occurred. The sub-option menu for processing option 1 is: bit description --- --------------------------------------------- 0 no sub-option selected 1 save complete mass array 2 save mass spectrogram/direct-event plot data ion count rate sub-option (0 or 1 for each bit) ==> To select option 1, enter '1'; to select option 2, enter '01'; to select both, enter '11'. Sub-option 1 saves spin data, the instrument parameter data structure, and the full ion count array in a binary file that will be processed further using tide_masses. The binary file has an .mss extension. The mass array needs to be associated with various instrument parameters. To guarantee that the instrument parameters are complete, the first spin saved is the first spin to be completely reported after the first superspin in the file or after the user-selected start time. If sub-option 2 is selected, the user indicates what count rate units are to be plotted: plot opt description --- ----------------------- 0 stop 1 log(hertz) 2 log(number flux) 3 log(energy flux) 4 log(phase space density) 5 log(counts) plot option => The user can specify the minimum and maximum count rates used to determine the colors used in the spectrogram: The default data range for non-zero counts is xx.xxxx to xxxxx.x Do you want to change it? (y/n) If the answer is 'y', the user is prompted for the plot minimum and maximum. If the answer is 'n', the range is set to the default values which are: default default actual actual units minimum maximum minimum maximum ------------------------ ------- ------- ------- ------- log(hertz) 1.0 7.0 0.727 7.048 log(number flux) 4.0 10.0 -0.550 13.403 log(energy flux) 4.0 10.0 2.342 12.577 log(phase space density) 10.0 18.0 2.895 22.674 log(counts) -1.0 4.8 -1.505 4.816 Sub-option 2 has to be run at the same time that the spectrogram display software, tide_spect.pro, is executed. The output is stored in masses.dat. Due to the size of the ion count array, a floating point array called masses(6,7,32,31), only one array at a time is passed from the processing software to the display software. The processing software waits for the display software to read and plot the data before any more data is processed. After tide_spect finishes plotting the data, it empties masses.dat. The processing software starts up again whenever masses.dat is empty. Both programs have to be running in order for any data to be processed or displayed. The processing software checks the content of masses.dat every second. The software stops if no new data is processed for two minutes. The sub-option menu for processing option 2 is: bit description --- ------------------------------------------ 0 no sub-option selected 1 save housekeeping bytes 2 convert and save as engineering data table housekeeping sub-option (0 or 1 for each bit) ==> If sub-option 1 is selected, spin information and the 46 housekeeping bytes are saved in a binary file with .hk as the extension. The housekeeping bytes are further processed using one of several housekeeping software programs used to convert the bytes to the actual engineering parameter value. See Section VII for details about the housekeeping byte processing software. If sub-option 2 is selected, the bytes are converted to the actual engineering value and the results stored in a table format every major frame (9.2 seconds) in a file with .eng as the extension. The sub-option menu for processing option 3 is: bit description --- --------------------------------------------- 0 no sub-option selected 1 save instrument parameter data structure 2 save instrument parameter data as text instrument parameter sub-option (0 or 1 for each bit) ==> Only one of the two sub-options can be selected, either enter '1' or '01'. If the user selects both, only option 2 will be done. The extension of the instrument parameter output file is '.ip'. For sub-option 1, it is a binary file that can be further processed by as yet unwritten software. For sub-option 2, it is a text file with each instrument parameter and option spelled out. The sub-option menu for processing option 4 is: bit description --- --------------------------------------------- 0 no sub-option selected 1 save direct events 2 save moments for every spin 3 save moments for complete report spins only (results saved in moments.dat) spin header sub-option (0 or 1 for each bit) ==> Sub-option 1 saves direct-event data in a binary file with a .de extension. The file contains current spin information and the 128 ion counts. Data in the file will be processed further using as yet unwritten software. Note: direct-event data are saved in direct_event.dat whenever option 1, sub-option 2 and/or option 5, sub-option 1 are selected. The direct_event.dat file is used by several plot routines to display direct-event data as count rate versus bin number line plots. Sub-option 2 saves spin, moments, and instrument parameter data for every spin in a text file with a .mom extension. Sub-option 3 saves spin, moments, instrument parameter data, and selected ion count rates in a large text file called moments.dat. The existing moments.dat file will be over-written. The exact format of these files has yet to be determined. Processing option 5 provides the same data processing options that the old get_spins and post_spins software provided for processing calibration mode data. The calibration mode sub-option menu is: bit description --- --------------------------------------------- 0 no sub-option selected 1 save singles/mass/direct-event plot data 2 save beam pulse test data 3 save singles data for chamber file data 4 save mass data for chamber file data calibration mode sub-option (0 or 1 for each bit) ==> The output for processing option 5 is identical to and used the same way as the output from post_spins and get_spins. For more details on this option, refer to the calibration mode software documentation. If sub-option 1 is selected, the software creates the plot files, masses.dat, direct_event.dat, and singles.dat, used by the calibration plot routines. Note: This option can not be run at the same time that processing option 1, sub-option 2 is run because they create the same files with different formats. If both are selected, the software will only process the science mode data. Sub-option 2 creates a file with extension .bpt used to determine the PCSGE and MAC spin counter offsets. The offset must be known before sub-options 3 and 4 can be run. If sub-option 2 and 3 or 4 are selected the following warning is given and neither option 3 or 4 are run: Option 2 can not be run with options 3 or 4. Neither option 3 nor 4 will be run. Sub-options 3 and 4 are used to combine the spin information from the LEIF chamber files with the singles (3) and mass (4) data in the telemetry files. The user is asked to enter the name of the LEIF lab chamber file: enter LEIF (Mac) chamber filename => The file must be in the directory pointed to by SUN_PATH. The next prompt: spin offset (telemetry - gse spin counter) => is the number that must be added to the spin counter in the chamber file to get the corresponding telemetry file spin counter, The beam pulse test is used for this purpose. See lab calibration software documentation for more details. The output filenames are the same as the chamber file but with different extensions, .sng for the singles data and .mss for the ion mass data. The output files are large text files that contain telemetry spin data, chamber file data, and all the singles or mass data for each spin in the chamber file. The files have the same format as the 'post_spins' output and are used as input to the contour plot routines. ---------1---------2---------3---------4---------5---------6---------7---------8 Processing option 6 creates a binary file (.sect0) containing spin information and the 256 integer count rates that TIDE could not process. The data is stored for only the first spin of each superspin and the counts should be at or near zero. Processing option 7 strips dump mode bytes from the telemetry stream and saves them in a binary file (.dmp) along with some data product and spin header information. Processing option 8 creates hex dumps of all of the mass count rate data products. This option is used for diagnostic purposes only. All the data product hex dumps for a specific spin are stored in a text file called spnnn.dat where nnn is the spin number. SWRI has provided a list of what each hex dump should look like. Once the software has prompted the user for all the information it needs, data processing starts. The first thing the processing software does is determine the size of each record read. The size varies depending on whether the instrument is in a regular flight mode or in contingency mode. The telemetry stream contains more than twice as much data in contingency mode. If the record length in not one of the two expected, execution stops with: Unknown level zero record length of xxxxxx To let the user known that the software is doing something, as each spin is processed, the spin number, date, time, number of data products, major frame counter, and record number are listed on the terminal. This spin listing can be long, so the TIDE level-zero processing software (tide_lz, tide_mf, cal_mf, and cal_lz) should be run from a non-scrolling window. If the software should abort for any reason, the last line on the terminal indicates where processing stop. lz_dump and byte_dump can be used to look at the telemetry to determine the potential cause of the processing error. Output data file content: The output files created vary depending on the option selected. The option descriptions given early in the section indicated the filenames or the file extensions created by each option. The following is a description of the content of each file. Browse the software for exact file formats. Most of the files are created by source code contained in get_spins.c or get_dp.c . .err file --------- This file contains processing information and error messages. The file is always created. All messages in the .err file contain the record, major frame, spin, and data product numbers and spin time. Examples of error/information that follows these numbers are: End of telemetry file Time sequence error: current msec: , prev.msec: Sync byte for the dp of spin not found where expected. Data product length exceeds remaining spin packet length. ,, Data product checksum error, calc = , expected = Data product spin counter different than expected. ,, Ran out of input before compression complete. Data product not processed or unknown Spin header checksum error, calc = , expected = .ip file -------- The .ip file contains instrument parameter data. For sub-option 1, it is a binary file containing spin and major frame number, spin time, and the instrument parameter data structure. It is intented to be used in other, as yet unwritten, processing software. The format of all the level-zero data structures are in $tide/sxr/tide_lz_stru.h, a C header file. For sub-option 2, the file is a text version of the data structure. Information is added to the file whenever an instrument data product (221 or 222) is read. masses.dat ---------- masses.dat can either contain calibration mode mass data or science mode mass data. The file is intended to be used with one of the spectrogram plot routines. The file contains plot labeling information and the image array of color indexes representing an ion count rate for completely reported spins. singles.dat ----------- singles.dat contains calibration mode singles data. The file is intended to be used by one of the calibration mode plot routines. It contains plot labeling information and the logged count rates for the energy/singles data. .dmp file --------- The .dmp file is a binary file containing dump mode data including: telemetry filename, spin and major frame number, spin time, and the 1024 bytes in the dump mode data product. .sect0 file ----------- The .sect0 file is a binary file containing the sector zero bin data. Data for the first spin of each superspin is reported and saved. .mss file --------- This is a binary file containing the bulk of the science mode data including spin amd major frame numbers, spin time, housekeeping bytes, instrument parameter data structure, ion count data products read and processed, and the ion count rates. The ion counts are in a floating point array that is 31 energy bins (high to low) by 32 spin angle bins by 7 channels by 6 masses. There are 167,447 bytes per completely reported spin, which means it is a VERY large file. The file is intended to be read by mass data processing software. IV. TIDE ion count rate processing software, tide_masses tide_masses is used to further process ion count rates. Its input is the unformatted file (extension .mss) created by option 1, sub-option 1 of one of the TIDE level-zero processing software programs: tide_lz, tide_mf, or cal_mf. The command to execute the program is: $tide/tide_masses The first user prompt is for the type of processing to be done: opt description --- ----------------------- 0 stop 1 color spectrogram plots 2 chromogram plot data processing option => The second prompt is for the name of the unformatted file created by tide_lz, tide_mf, or cal_mf that contains the ion count rates and associated information. ion count rate filename => Option 1 creates the same output as option 1, sub-option 01 of tide_lz, tide_mf, or cal_mf. The requested information is also the same, the user indicates what count rate units are to be plotted: unit opt description --- ----------------------- 0 stop 1 log(hertz) 2 log(number flux) 3 log(energy flux) 4 log(phase space density) 5 log(counts) plot option => The user can specify the minimum and maximum count rates used to determine the colors used in the spectrogram: The default data range for non-zero counts is xx.xxxx to xxxxx.x Do you want to change it? (y/n) If the answer is 'y', the user is prompted for the plot minimum and maximum. If the answer is 'n', the range is set to the default values. The spectrogram plot routine, tide_spect, must run at the same time as option 1. Start tide_spect first from one screen window and then start the plot routine from a separate window. For option 2, tide_masses provides the following options for creation of input to the chromogram display software: opt description --- -------------------------------------- 0 stop 1 generalized chromogram input data 2 TIDE energy chromogram input data 3 TIDE polar angle chromogram input data 4 TIDE spin angle chromogram input data output option => The next prompt is for the output file name, with no file extension: output filename (no extension) => The extension is set by the program and indicates the file content. Next the user indicates the output units, whether or not they ar logged, and the plot range: unit opt description --- ------------------- 0 stop 1 hertz 2 number flux 3 energy flux 4 phase space density 5 counts output units option => 1 linear(1) or logarithmic(2) output => 2 The default data range for non-zero counts is 1 to 7 Do you want to change it? (y/n) n If output option 1 is selected, tide_masses creates the text header file, extension .hdr, and the binary count rate file, extension .bin, used by the generalized chromogram program. The generalized chromogram program is documented separately. tide_masses assumes that the 3-D chromogram array is energy, spin angle, polar angle count (flux) arrays for a specific ion mass. The user is prompted for that mass: 0 H+ 1 He++ 2 He+ 3 O++ 4 O+ 5 Singles output mass number => 4 The mass labels listed in the table are currently hard-coded. Once the process for determining the actual mass has been determined, tide_masses will need to be modified so that the labels accurately describe the masses. The generalized chromogram plot has three title lines. The first two should be a short description of the data in the file, including the instrument name and ion species. Each line should be 40 characters or less. The third line describes the time and is automatically created by the software. The user is prompted for the first two title lines: 1st plot title line: 2nd plot title line: The title lines can be modified by simply editing the .hdr file. The format of the header file is given in the chromogram documentation. For options 2, 3, and 4, the user is prompted for single title line that should summarize the data: plot title line: The title should not include the instrument name or the date and time. That labeling is automatic. For output option 2, tide_masses creates the binary color images for the TIDE-specific chromogram plot where the colors are based on RPA voltage. The user is prompted for the red/green/blue color boundaries used to calculate color: Enter chromogram color limits. The RPA voltage range is x.xxx to x.xxx minimum red: red/green boundary: middle green (label only): green/blue boundary: maximum blue: For output option 3, tide_masses creates the binary color images for the TIDE-specific chromogram plot where the colors are based on the polar channel number. The user has two choices for the polar angle chromogram color bins: polar angle color bins --------------------------- opt 0: stop opt 1: red - channel 1,2,3 green - channel 4,5 blue - channel 6,7 opt 2: red - channel 2,3 green - channel 4,5 blue - channel 6,7 polar channel option => The user must also specify what variable to display on the horizontal axis: energy(1), spin angle(2) horizontal axis => For output option 4, tide_masses creates the binary color images for the TIDE-specific chromogram plot where the colors are based on the spin angle. The user is asked to enter the color boundaries: Enter chromogram color limits. red/green boundary: green/blue boundary: red/blue boundary: For option 2, tide_masses creates a file with '_cg.rpa' as the extension; for option 3, the extension is '_cg.pol'; and for option 4, the extension is '_cg.spn'. The files contain labeling information and chromogram color index arrays for each spin in the .mss file. There are currently three separate routines used to plot the chromograms. The command files used to plot them are cg_polar, cg_rpa, and cg_spin. V. TIDE level-zero display software mass spectrograms, tide_spect ----------------------------- tide_spect is the PV~WAVE plot routine used to display ion count rates as a function of RPA voltage and spin angle for each sector for either 7 or 14 completely reported spins for a user-specified mass. The mass can be changed interactively at any time during program execution. The software receives a spin of data at a time from tide_lz, tide_mf, or tide_masses. The processing program must be running at the same time as the plot routine. Each program needs to be run from a separate window. The plot routine should be run from a window located in the lower-left corner of the screen. It must be run from PV~WAVE (command: wave). Start the processing program first, then the plot routine using: wave> @$tide/run_spect run_spect is a PV~WAVE command file that compiles and runs the source code contained in the following files: $tide/pvwave/label_spect.pro procedures used to label spectrogram $tide/pvwave/load_color.pro procedure to create color table $tide/pvwave/plot_spect.pro procedures to plot spectrogram and modify labels $tide/pvwave/tide_spect.pro main procedure controlling the spectrogram The user is prompted for some initial plot information including the type of color to be used: color (1), grayscale(2) => text for the second title line: 2nd title line => The first title line is always 'TIDE Summary Plot'. The user determines whether 7 or 14 spins of data are displayed: spins/display (7 or 14) => Hardcopy plot files can be generated at any time during a run by pressing the 'h' key. The user can automate the hardcopy process: automate hardcopy (y,n)? => Plot files are automatically created every page (7 or 14 spins). During program execution, the user controls the display through a series of keystrokes. A small display window lists the keys and what they do: __________________________________________ | p pause 0 mass 0 | | h hardcopy 1 mass 1 | | r mirror ratio curves 2 mass 2 | | c ch.1 spectrogram 3 mass 3 | | 4 mass 4 | | q quit 5 singles | | | | mouse must be in PV~WAVE execute window| ------------------------------------------ The display is updated with new spin data in realtime every 6 seconds, in post- processing about every 3 seconds. The display updating will stop temporarily with a 'p'. The display is started again by pressing any key. If the display is stopped or no data is received for more than 100 seconds, the program will automatically stop executing. The program can also be stopped with 'q'. An 'h' will create a postscript plot file of the screen after the next set of spin data is added. The name of the postscript file is color_nnn.ps, where nnn is the most recent spin counter. The first mass displayed is always mass 5, singles. The mass can be changed by pressing a number between 0 and 5. The initial spectrogram displays all 7 channels. The channel 1 spectrograms can be replaced mirror ratio curves with values of 0 to 1 on the horizontal axis and RPA voltage on the vertical axis. 'c' will replace the mirror ration curves with channel 1 spectrograms. V. TIDE level-zero display software (con't) TIDE chromograms: tide_cg_polar, tide_cg_rpa, tide_cg_spin ----------------------------------------------------------- Currently, there are three separate PV~WAVE (IDL) procedures used to plot TIDE chromograms: tide_cg_polar.pro, tide_cg_rpa.pro, and tide_cg_spin.pro. They plot chromograms for all six masses (including singles) for each completely reported spin. The input file for each routine is created by option 3 for tide_masses. Each routine is run from a command file: cg_polar, cg_rpa, or cg_spin. The command files are run from PV~WAVE using the @ command. The first user prompt determines the number of spins on the display. For cg_polar, there can be either 8 or 16 spins. For cg_rpa and cg_spin, there can be 22, 33, or 66 spins per display. Hardcopy plot files can be generated at any time during a run by pressing the 'h' key. The user can automate the hardcopy process by answering 'y' to the second prompt: automate hardcopy (y,n)? => Plot files are automatically created every page. The next prompt is for the name of the chromogram data file created by tide_masses: chromogram filename => During program execution, the user controls the display through a series of keystrokes. A small display window lists the keys and what they do: __________________________________________ | p pause | | h hardcopy | | q quit | | | | mouse must be in PV~WAVE execute window| ------------------------------------------ All other information required by the plot routines are contained in the chromogram file created by tide_masses. VII. Utility software byte_dump lz_dump housekeeping byte_dump --------- byte_dump reads any binary file and puts user-selected bytes in a text file. There are 20 bytes per line (0 to 255) for a decimal file and 32 bytes per line (00 to ff) for a hex file. The user prompts are: binary filename => output filename => How many bytes do you want skipped? How many bytes do you want save (0 for all remaining)? decimal (1) or hex (2) dump? lz_dump ------- lz_dump reads a TIDE level-zero binary file and saves user selected major frame bytes in a text file, a minor frame per line (21 bytes). User prompts are: level zero data filename => output filename => How many major frames do you want skipped? How many major frames do you want save (0 for all)?