Instructions to create daily TIDE Instrument Command Request Lists (rqls)
-------------------------------------------------------------------------

This document was updated 09/23/05.

Once a week, on Tuesday morning, 7 new RQLs need to be created, verified by 
at least two people (usually Paul Craven and Peggy Sloan), and emailed to GSFC 
for validation.  They must be emailed to GSFC before 1:30 pm local time on 
Friday.  The current schedule for creating RQLs is the ones created on Tuesday
cover the period started on Friday of the following week, ie: doy-of-year for 
Tuesday + 10 is the starting doy-of-year.

The filename is tiddoy.rql, where doy is the day-of-year of the file.  The file
format is hardcoded in order to meet very strict guidelines.  Once the file has
been created, it can be manually edited to include non-routine commanding.

All mission RQLs are stored in /export/data/tide/command/rql/yyyy, where yyyy is
the year.

All commanding is done from the tidops account on griffin.


Creating the Polar Orbit Daily .pdf files
-----------------------------------------

Before creating the rqls, you need to put 8 orbit files starting with the doy 
of the first new rql.  The 8th one is needed to make sure that there is no 
problem with day crossings for the last rql created.  The orbit pdf files are 
in /export/data/tide/command ($tide/command).  Edit the cp_orbit file in that 
directory to include the 8 new orbit files.  The run cp_orbit to copy the files
to the web site http://satyr.msfc.nasa.gov/tideteam/RQL/.

Make sure that the date the orbit plot files were created is at least one day 
after the date on the latest 70-day orbit file (see /datafiles/orbit/pre).  If 
the orbit plots are not current, they will need to be recreated.  From idl, run
@plot_gsml.  Create only postscript (no gif) files.  The software will convert 
the postscript files to pdfs.  Note: it takes a long time (~60 minutes) to 
create the 70 new orbit files.  Peggy Sloan usually creates them.  They need 
only be redone whenever there is a new 70-day orbit file which is usually just
once a month.  The new file usually comes down on the third Thursday of the 
month and contains orbits for 70 days starting with the date of the third 
Wednesday of the month.

plot_gsml prompts:

Orbit file (yyymmdd_v0n) =>
Enter yyyydoy (-1 for entire file) =:
Enter l shell to be plotted=:
Enter l shell for Np to Eq =:
Enter l shell for Eq to Sp =:
Enter l shell for Sp to Eq =:
Enter l shell for Eq to Np =:
Do you wish screen output (y/n)? 

The orbit file in in /datafiles/orbit/pre.  Always plot the entire file (-1). 
Always plot an l-shell of 7.  Use the l-shell cutoffs in the last line of 
lshell.cutoffs in /export/data/tide/command.  Answer 'n' for output.



Creating the TIDE Daily Instrument Request Lists (RQLs)
-------------------------------------------------------

To create the rqls, log into the tidops account on griffin.  
Either   cd /export/data/tide/command  or  cd $tide/command
Get into idl and type @command, you will be prompted for all necessary 
information.

The first prompt determines the type of processing:

       0 - stop
       1 - create new files
       2 - send existing files to GSFC

      what next =>

Note:  Currently all files created need to be reviewed by at least one other 
       person before the are sent to GSFC, so option 2 is currently not 
       available.

The second prompt asks for the name of the individual responsible for the file
and its content:

       0 - stop
       1 - P.D.Craven
       2 - M.O.Chandler
       3 - other
       
      observer code => 

Unless otherwise instructed, enter 1 (Paul Craven).

The next prompt determines the filetype.

       0 - stop
       1 - instrument request
       2 - activity file
       3 - macro file
       4 - microprocessor request file
       5 - real-time command file
       6 - principle investigator text file

      file type =>

For rqls, enter 1.  See command.txt for a discussion of the other options.

The user prompts are:

      day of year of first file =>
      number of daily files to create =>
      working orbit filename (yyyymndd_v0n) =>

Check /export/data/tide/command/rql/yyyy to find out what the last rql was in 
order to determine what day-of-year (doy) to start with.  Unless otherwise 
instructed, create 7 daily files.  Check /datafiles/orbit/pre to determine the 
name of the latest 70-day predicted orbit file.  There is a new file once a 
month, usually on the Thursday after the third Wednesday.  The date of the file
will coincide with the third Wednesday of the month.

The next four prompts determine what L-Shells to base the radiation belt 
instrument off/on sequences on.  Unless otherwise instructed, use 4 5 6.5 7.  
The file call lshell.cutoffs in /export/data/tide/command/ indicates the ranges
of the l-shells to use.  The last line indicates the most recently used set.

      Enter L-Shell cut-offs for each node.
      Enter 0 for on off/on pair to skip turn-off
      North Pole to Equator (MCP off) =>
      Equator to South Polar (MCP on) =>
      South Pole to Equator (MCP off) =>
      Equator to North Pole (MCP on) =>

Each quadrant L-Shell crossing has been assigned a numeric code (1-4) in the
same order as they are listed above.  As the software creates the rql, it lists
on the screen the last l-shell crossing for the previous day and all the 
l-shell crossings for the current day.  An example:

      L-Shell crossing: count,  doy, hhmmss, and type: 

      0  182 153309  2
      1  182 085857  1
      2  182 094715  2
      3  182 105634  3
      4  182 131426  4

Whenever any of the L-Shell crossings are not found, you will receive a 
warning message indicating that an crossing was not found.  These are usually
not a problem but look at the orbit plots on the web site at 
http://satyr.msfc.nasa.gov/tideteam/RQL/ as you create the rqls to make sure 
the crossings match.  Note:  Occasionally, the orbit plot will indicate an 
l-shell of 7.0 for the eq-np without an sp-eq l-shell crossing.  In this case, 
the off/on command sequence is skipped.  The commanding at the eq-np crossing
startes a minute before the crossing.  All other commands start at the time of
the crossing.  Warnings and prompts printed when orbit problems are encountered
are discussed below.  Every other day (even number doy), commands for a 
background check are included in the rql.

You will receive the next two prompts for each rql:

      List completed file? y/n =>
      Save completed file? y/n =>

Answer y to both prompts.  Use the screen listing to verify the cutoffs with
the orbit plots.

All instrument request lists are stored in the rql subdirectory.  After you 
have created the RQLs, use cp_rql in the rql subdirectory to copy them to the 
web site.  After verifying that all the orbit and rql files are on the web, 
send an e-mail to Paul Craven letting him know that they are ready for his
review.

If Paul indicates that changes need to be made to one of the files, do it very
carefully using the vi editor.  If you change the time of a background check 
there is a file you must edit to correct/add the time: 

       cd /export/data2/tide/db/exe/
       vi mask_run_times.txt

Go to the line containing the date of the background check or nearest to the 
new background check.  Either correct the start/stop times or add a new line 
with the date/times.  The stop times are 20 minutes after the start times.

Once the changes have been made and you also reviewed the files using the web
site, the rqls need to be send to GSFC for validation and uplink to TIDE.  

In /export/data/tide/command/rql, edit send_mail and change the names of the
7 files.  Type 'send_mail' to send the files to GSFC.  Validation reports will
be emailed to the tidops account on griffin.  Save each validation report in a
separate file called tiddoy_rql.rpt.  There will usually be two validation 
reports one each from two machines at GSFC.  The 's tiddoy_rql.rpt' command in
mail will automatically append the two reports in the same file.  Once you have
verified that all the rqls are valid, move the validation reports to the 
/export/data/tide/command/valid_rpt/rql/yyyy directory.  The move the RQLs in 
/export/data/tide/command/rql directory to the yyyy subdirectory.

If you have any problems or questions about sending the RQLs to GSFC, first 
contant Bob Gardiner (301-286-0723 rgarsine@pop400.gsfc.nasa.gov) or John
Wainwright (301-286-0724 jwainwri@pop400.gsfc.nasa.gov).


Redoing rqls that have already been done
----------------------------------------

Occassionally, rqls will need to be redone.  This usually happens when a new
70-day orbit file comes down in association with a Polar Spacecraft flip or 
when it is necessary to change the l-shell crossings because of changes in the
Polar Orbit.  Several things need to be done before you rerun the IDL code.
First move, delete, or rename the original rql's in 
/export/data/tide/command/rql.  Then in /export/data/tide/command, 

   more last*

The file 'last' should have the last crossing for the previous week, 
last.crossing should have the last crossing for the current week.

Each file contains a single line with the format 'hhmmss n doy'.  
hhmmss is the hour, minute, and second of the last crossing, n is the 
type of crossing:   1 - north pole to equator
                    2 - equator to south pole
                    3 - south pole to equator
                    4 - equator to north pole

and doy is the day of year of the last crossing on the day before the
next rql to be created.

If you are redoing the entire week then simply:

      cp last last.crossing

Then rerun the idl @command software.

If you are redoing just one rql, find out the time and type of the last 
crossing on the day before.  Copy last.crossing to a temporary file.  The
edit last.crossing and put in the new information.  After you have run the
IDL code, rename the temporary file back to last.corssing.

If the rql(s) you redid have background checks then issue the following 
commands:

      cd /export/data2/tide/db/exe
      vi mask_run_times.txt

Go to the end of the file and delete the duplicated mask run times.


Changing the source code
------------------------

The source code may need to be changed to accomodate changes in the orbit when
selecting the time for background checks.  Other possible changes may also
occur.  The 'sloan' account is current owner of the source code.  The code is in
/export/data/tide/command/sxr/.  For background checks, changes will need to be
made to the procedures create_rqls get_lshell_crossings in command_util.pro.



Potential warnings and errors and what to do about them
-------------------------------------------------------

The software keeps track of the last l-shell crossing of the last rql created.
That way it can make sure that for every turn-off there is a turn on even if
they are a day apart.  If you get the following message, cntl-c out of the
software, get out of IDL, review both last.crossing and the last rql created to
locate and correct the problem.  Do not proceed until the problem has been 
corrected.

      ************************** WARNING ******************************

      The information in last.crossing does not match current doy
      Check tiddoy.rql to make sure command sequence is OK.

If the information in last.crossing does not match the last rql created, the 
file can be manually edited and the last crossing changed.  See redoing rqls
below for more detail on changing the last.crossing file.


Instrumentors are not permitted to issue commands for a 6 minute period around
midnight.  If l-shell crossings occur in the time frame, the software adjusts
them.  No action is necessary for these two warnings:
                      
      *******************  WARNING  *****************************
                      
      An l-shell crossing happens too late in the day, hh:mm:ss
      The turn off has been moved to 23:57:00
                      

                      
      *******************  WARNING  *****************************
                      
      An l-shell crossing happens too early in the morning, hh:mm:ss
      The turn on has been moved to 00:03:00
                      
      

If you get one of the next two warnings, as soon as you finish creating the 
rqls, before you print them, edit the listed file and include the fix:

      *******************  WARNING  *****************************
                      
      An l-shell crossing happens too early in the morning, hh:mm:ss
      The turn off must be moved to day doy
      Edit its rql and include fix_rql.doy
      at the end of the file.
                      
                      
      *******************  WARNING  *****************************
                      
      An l-shell crossing happens too late in the day, hh:mm:ss
      The turn on must be moved to day doy
      Edit its rql and include fix_rql.doy
      at the beginning of the file.
                      


The POLAR spacecraft orbit has shifted enough that at times it does not pass
through the radiation belts.  At those times, it is not necessary to turn 
down the TIDE MCPs.  You will get a pair of warnings when this happens:

      *************************  WARNING  **************************
               
      The L-shells you have chosen have resulted in an Equator
      to South Pole MCP on with no corresponding off.
               
               
      *************************  WARNING  **************************
               
      No South Pole to Equator L-Shell crossing was found, so the
      South Pole to Equator to North Pole off/on sequence was skipped.
               
               
or 
               
      *************************  WARNING  **************************
               
      The L-shells you have chosen have resulted in an Equator
      to North Pole MCP on with no corresponding off.
               
               
      *************************  WARNING  **************************
               
      No North Pole to Equator L-Shell crossing was found, so the
      North Pole to Equator to South Pole off/on sequence was skipped.
               
               
You will be asked whether or not to continue.  Unless otherwise instructed,
answer 1 (yes).  The pass will be skipped.  A warning comment will be added to
the appropriate rql.

      Check your orbit plots to make sure this is not a problem.

      Do you want to continue? no(0), yes(1)? =>
               

If the off/on sequence is less than ten minutes long, you will be asked if you
want to skip the pass:
                 
      *************************  WARNING  **************************
                 
      Your MCP off/on sequences is less that 10 minutes in length.
      h1m1s1 - h2m2s2
                 
                 
      Check your orbit plots to make sure this is not a problem.
                 
      Do you want to turn off no(0), yes(1)? =>