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:
      <name of directory containing the telemetry>

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 <telemetry filename, including path>

Whenever a new telemetry file is opened, the user is informed with:

     Processing of <telemetry filename>  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.  <filename>.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 <filename>

      Time sequence error: current msec: <msec>, prev.msec: <msec>

      Sync byte for the <nth> dp of spin <nnn> not found where expected.

      Data product length exceeds remaining spin packet length.
      <dp length>,<byte_position in spin packet>,<spin_length>

      Data product checksum error, calc = <nnn>, expected = <nnn>

      Data product spin counter different than expected.
      <dp id>,<dp header spin id>,<expected spin id>

      Ran out of input before compression complete.

      Data product not processed or unknown

      Spin header checksum error, calc = <nnn>, expected = <nnn>

.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)?