PURPOSE --
 Schedule SNAP SU's onto a cclist.
 
 DEVELOPER --
 Gary Bower and Merle Reinhart
 
 KEY --
 allowed_options = a list of legal options on the command line.
 args = a list containing the arguments from the command line.
 begin_time_x,y = the scheduled begin time used in cmp_begin_time.
 calendar_commands = a list of commands for the calendar -report jobs.
 cclist = a dummy variable for looping.
 ccl_intermed = the intermediate ccl object during snap iterations.
 ccl_final = the cclist to which snaps have been scheduled,
    expressed as a ccl_util object.
 ccl_start = the cclist to which to schedule snaps, expressed as a 
    ccl_util object.
 ccl_tend = the end time of input_cclist.
 ccl_tstart = the start time of input_cclist.
 comlist = a list of containing calendar commands to do the calendar
    -report jobs.
 curcyc(0,1) = snap pool names for the current cycle.
 current_command = a string holding the current command while being constructed.
 current_cycle = the current cycle from the command line expressed as 
    an integer.
 cur_cyc = a string denoting the delta cycle number of a snap pool.
 cur_rec = an integer counter marking the current record in grecs.
 cur_sus_files = a list of SU files (list).
 cycle = the current proposal cycle (integer or string).
 cycle_pool = a dummy variable for looping over the snap pools.
 cyc_name = a string representing the cycle number of a snap pool.
 dbConn = a stpydb object that connects to the database.
 dict = a dummy variable for iterating over a list of dictionaries
    obtained from snap_dict.
 e = a dummy string needed for iterating over a list of errors.
 elapsed_time = the time required for running this tool, expressed
    as a time_util object.
 errors = a list of logfile lines containing the case-insenstive string 
    'error'.
 errors_list = a list of error messages.
 factor = a string showing the percentage of a snap program that has
    been scheduled.
 file_snap_sus = a temporary file name to which snap_sus are written.
 first_line = a string containing the first line in snap_temp_file.
 g = a file object to which output is to be written.
 gaps = the filename of the gaps file generated from ccl_final.
 grecs = a list of lines in snap_temp_file.
 header = removal of the first element in grecs.
 i = a dummy variable for looping.
 inequality = converting snap_key from alphanumeric to a mathematics
    logical operator.
 input_cclist = the input cclist converted to a ccl_util object.
 j = a dummy variable for looping.
 key = a dummy string needed for iterating over a list of keys.
 line = a dummy string needed for iterating over a list.
 lines = a list of lines in an input file.
 niter = the integer number of snap iterations that have been started.
 no_snaps = a Boolean variable indicating if there are no snaps that
    can be scheduled.
 node = a dummy string needed for looping over the nodes list.
 num_pools = the integer number of pools provided in snap_temp_file.
    This is currently set to 4, but may need to be changed if there is
    a change in policy regarding snap programs from previous cycles.
 options = a dictionary containing the options and values in args.
 outfile = an output file object.
 output_file_dict = a dictionary of calendar -report output files,
    sorted by snap pool.
 output_root = the root name of the output log and report files.
 ow = a file object to which output is to be written.
 parms = a list of parameter values in args.
 place = a dummy string needed for temporarily holding a place SU string.
 places = a list of unique places in the cclist.
 pool = a dummy string for iterating over the keywords in snap_dict.
 pools = a list of snap pools in order of priority.
 pool_file_name = the file name containing one of the initial pool of SU's.
 pool_file_names = a list of file names containing the initial pool of SU's.
 pool_name = a string converting which_pool to alphanumeric.
 pool_num = an integer denoting which snap pool is being read.
 prevcyc(0,1) = snap pool names for the previous cycle.
 re_err = a compiled regular expression to find errors.
 re_warn = a compiled regular expression to find warnings.
 result = a list of dictionaries containing the results of a query.
 rptfile = the report file object.
 run_letter = the letter to be used in the intermediate cclist name (string).
 save_name = the string name of an intermediate cclist.
 save_stdout = a copy of the sys.stdout file object.
 score = a dummy integer needed for temporarily holding an SPSS score.
 score_x,y = the SPSS score of an SU used in cmp_score.
 sn_num = the number to be used in the intermediate cclist name (integer).
 snap_cutoff = a string repesenting the fraction of snap program completion.
 snap_cutoff_str = a string used to help determine snap_cutoff.
 snap_dict = a dictionary containing the snap information sorted by pool.
 snap_dict_list = a list of dictionaries showing the schedule snap data
    determined by the calendar -report jobs.
 snap_dict_short = a subset of SU data from snap_dict with unique places.
 snap_key = a string denoting which key in snap_dict is to be used.
 snap_sus = a list of snap SU's that are schedulable on the cclist.
 snap_temp_file = a list of gimme_snaps temp files
 su = a dummy string needed for temporarily holding an SU string.
 successful_sus = a list of snap SU's that are scheduled on ccl_final
    according to its gaps report.
 sunit_id = the SU name expressed as a string.
 sus = a list of SU's scheduled on ccl_start.
 su_dict = a dictionary containing the scheduling data for a given
    snap SU determined by the calendar -report jobs.
 su_dict_list = a list of dictionaries showing the schedule snap data
    determined by the calendar -report jobs.
 temp? (where ? = 1 or 2) = temporary variables.
 temp_cclists = a list of temporary cclists.
 time = a list for keeping track of clock time at start and stop of tool run.
 tcycle = the cycle from which the SU list is drawn (integer).
 tpool = the pool priority of the SU list (string). This has values of 'l'
    or 'g'.
 tend = the end time before which to schedule snaps expressed as a
    time_util object.
 tstart = the start time after which to schedule snaps expressed as a
    time_util object.
 w = a dummy string needed for iterating over a list of warnings.
 warnings = a list of logfile lines containing the case-insenstive string 
    'warning'.
 which_pool = a string denoting from which pool a snap SU is.
 week = the week id parsed from the snap_temp_file expressed as a string.
 week_id = week converted to a time_util object.
 wrapped_cmd = currrent_command plus UNIX shell wrappers.
 x = a dummy variable to hold a value temporarily.
 y = a dummy variable to hold a value temporarily.
 ?_num (where ? = b, c, d, e, x, y, and z) = counters needed for intermediate
    cclist names (integer).
 
 CODE ALGORITHM --
 1. Parse the command line.
 2. Check that the command line start and end times intersect the
    input cclist.
 3. Get the current cycle from ASSIST_DB.
 4. Get the *temp file produced by gimme_snaps.
 5. Get the week id and snap cutoff percentage from the *temp file.
 6. Determine the names of output files and open them.
 7. Parse the *temp file into initial pool SU files.
 8. Create the calendar -report jobs that will determine which
    SU's are schedulable on the cclist.
 9. Run the calendar -report jobs.
10. Parse the calendar -report output files into the dictionary
    snap_dict, which gives the place and SPSS score data for each
    schedulable SU.
11. Output snap_dict in a report file.
12. Create a short list of snap_dict where each snap candidate
    has a unique place on the cclist.
13. While there are schedulable snaps, add the snap candidates
    to the cclist and schedule them. Keep track of which snap
    candidates actually schedule. Repeat steps 8-13 until there
    are no more schedulable snaps.
14. Save the final cclist.
15. Report which snaps have been scheduled.
16. Delete temporary cclists.
17. Search for warnings and errors.
 
 NOTES --
 This tool will not necessarily raise an error if a bad SU is
 encountered. Any such errors are reported at the end of the
 log file. Check the output log file for any error messages. For
 example, if a candidate SU fails to add to a cclist, the
 error message is:
 ERROR: CCL is being restored to original state before running
 this command.
 
 The work-around is to edit the file yyddd_snap_sus.temp created by
 gimme_snaps in the calendar working directory. Two edits are required:
 (a) delete the bad SU, and (b) determine which pool the bad SU was
 in, and decrease the number of SU's in the pool by one. This number
 can be found by starting from the bad SU and scrolling upwards until
 one encounters a line with only one integer value at the start of a
 snap pool.
 
 Then run this tool again.
 
 MODIFICATION HISTORY --
 Date        Who            What
 ====        ===            ====
 05/02/07    Bower          initial implementation.
 05/15/07    Bower          Delete the temporary cclists.
                            Fix bug in get_gap_data.
 05/16/07    Bower          Add try/finally logic.
 06/05/07    Bower          Fix bug in log file appending.
 06/26/07    Bower          Print command line to log file.
                            Don't print snap dictionary to log file;
                            see the rpt file instead.
                            Fix typo in default value of output_root.
                            If a candidate list is empty, then skip.
                            Start each calendar -report job with
                            ccl_start, not input_cclist.
                            Improve elapsed time report.
 07/31/07    Bower          Redesign algorithm for enhanced speed.
                            Get current_cycle from assist.
                            Improve assignment of output filenames.
 12/07/07    Bower          Get snap cutoff percentage from temp file.
 12/12/07    Bower          Fix typo.
 06/27/08    Bower          Add documentation note on bad SU's.
 08/08/08    Bower          Print intermediate cclist names to output.
 11/05/10    Bower          Fix bug in SU sorting.
 12/13/11    Bower          Abort if bad SU is encountered during candlist -addsus.
 12/14/11    Bower          Add Merle's function check_for_usable_su.
 03/22/12    Chance         Remove harry and potter from FAST_CPUS
 09/26/12    Bower          Fix bug in determining cycle boundary.
 11/16/12    Bower          Compatible with new version of su_gaps.
 12/04/12    Reinhart       Allow the cale -report commands to execute in parallel
 08/26/15    Bower          Specify start and end times explicitly

Modules
		calendar_util ccl_util file_util glob os re spss_sys_util spst_getopt stpydb string su_gaps su_util sys time_util types

Functions
		check_for_usable_su(sunit, ccl_start, ccl_end) This function performs a check that the input SU won't cause candlist -addsus to choke.   Input:   sunit     - scheduling unit as an su object                or a string in sssssss[:vv] format   ccl_start - cclist start time as an spss_time object                or a string in YYYY.JJJ:HH:MM:SS format   ccl_end   - cclist end time as an spss_time object                or a string in YYYY.JJJ:HH:MM:SS format                 Output:   True|False - scheduling unit is ok or not to pass to -addsus cmp_begin_time(x, y) Comparison function for sorting a list of scheduling begin time in a cclist. cmp_score(x, y) Comparison function for sorting a list of scheduling place lines obtained from a calendar report. convert_keyword(key, current_cycle, snap_cutoff) Convert a snap_dict keyword to pool_file format. convert_pool(pool, current_cycle, snap_cutoff) Convert pool_file format to snap_dict keyword. make_report_jobs(input_cclist, current_cycle, week_id, tstart, tend, cur_sus_files, snap_cutoff, niter) This tool will create the cclist operations to be distributed among different cpu's.   Input:  input_cclist - name of cclist to start with         current_cycle - current cycle of proposals         week_id - YYDDD format         tstart - start time of calendar report in YYYY.DDD:HH:MM:SS         tend - end time of calendar report in YYYY.DDD:HH:MM:SS         cur_sus_files - a list of files containing SU's         niter - the number of snap scheduling iterations   Output: a list containing the calendar commands         to do the calendar -report jobs.   Returns: calendar_commands (a list of calendar commands),          a list of temporary cclists created by running calendar_commands make_su_lists(snap_temp_file, current_cycle, snap_cutoff, save_stdout, tstart, tend) This tool will parse the gimme snap temp file into the appropriate initial pool su lists. parse_report_output(week_id, output_file_dict, snap_cutoff) Parse the calendar -report output files to produce the intermediate files needed to run cale -addcand. parse_su_candidates(snap_dict) Parse the SU's out of snap_dict to get a list of SU's. parse_the_reports(file) Parse a calendar -report output file. print_snap_gaps(ccl_final, snap_sus, save_stdout) Print a summary of SU gaps data from snap_sus. run(*args) Schedule SNAP SU's onto the input cclist.   Usage: do sched_snap_sus <input_cclist> <start time> <end time>  [-output_root=<output_file_name_root>]   where <input_cclist> is the name of the cclist to which snaps will be added, and <start time> and <end time> are the start and end times in YYYY.DDD:HH:MM:SS format where snaps can be scheduled.  Options: -output_root=<output_file_name_root> : redirect the output to              files with this root name. The default is to set              output_root to <weekid>_snap_sus. Higher versions              default to appending '_<version number>. The suffix              names of the output files include '.log' and '.rpt'.   Example: do sched_snap_sus gab141d1 2007.141:00:30 2007.147:23:40  -output_root=07141_snap.sus_2 run_report_jobs(comlist) This tool will run the cclist operations distributed among different cpu's.   Input:  comlist = a list of cclist and calendar commands   Output: spss_sys_util.SUCCESS schedule(snap_dict, snap_dict_short, snap_key, tstart, tend) Using snap_dict, schedule the candidates. write_pool_rpt(rptfile, current_cycle, snap_dict, snap_key) Write the snap pool report to open file object rptfile.

Data
		FAST_CPUS = [['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ['daffy.sogs.stsci.edu', 'planinst'], ['bugs.sogs.stsci.edu', 'planinst'], ...] LOGNAME = 'planinst' __version__ = '08/26/15'