Instructions for ~rmaddale/bin/forecastsCmdLine

Ronald J Maddalena
September 9, 2014

The script forecastCmdLine underlies the 'cleo forecasts' GUI as well as the Dynamical Scheduling System

forecastsCmdLine -- Generates high-frequency weather forecasts or postcasts and
                     saves results to files within a time-stamped directory.
 
 SYNOPSIS
     forecastsCmdLine [ -h | -help ] [ -model ( NAM | GFS3 | RUC ) [ -quiet ]
                      [ -sites listOfSites ]  [ -readCaches ] [ -writeCaches ]
                      [ -average ] [ -whichOpacities listsOfOpacTypes ]
                      [ -calculate thingsToCalculate] [ freqList listOfFreqs ]
                      [ -elevTsys elevation ] [ -elevRefracAirMass elevation ]
                      [ -desiredTime timeDate ] [ -startTime timeDate ]
                      [ -stopTime timeDate ] [ -incrTime numHrs ]
                      [ -startFreq freq ] [ -stopFreq freq ] [ -incrFreq freq ]
                      [ -startElev elev ] [ -stopElev elev ] [ -incrElev elev ]
                      [ -startOffset offNum ] [ -stopOffset offNum ]
                      [ -PointMap ] [ -CoeffModel ] [ -hghtLimit meters ]
                      [ -mimicHistorical ] [ -saveAll ] [ -fastCalc ]
 
DESCRIPTION
    A command line program for generating the CLEO high-frequency weather
    forecasts and postcasts.  Those wanting to use a GUI interface should try
    the 'cleo forecasts' utility instead.  'cleo forecasts' acts as a frontend
    to this command line program.
 
    For documentation on the models, terminology, etc, and to see the latest
    forecasts generated by this program, go to:
        http:/www.gb.nrao.edu/~rmaddale/Weather
 
    The program has a rich set of arguments that allows one to select the
    set of calculations that are to be performed, plus specify the set of
    parameters used by those calculations.  Processing can be rather CPU
    intensiveso I suggest calculating only what one wants.  Or, one can just use
    the defaults which are identical to what is performed when updating the CLEO
    High Frequency weather pages.
 
    The results of this program are a set of files that are placed in a newly-
    created subdirectory of the current directory.  One must have write
    permissions to the current directory.  The name of the directory will be:
        Forecasts_yyyy_mm_dd_HHhMMmSSs
    where yyyy, mm, ... represent the UT date/time of when this program was run
 
    The directory will contain a 'Parameters_*' file that will summarize what
    the user specified when the forecasts were generated.  Each site and class
    of calculations will be stored in similarly time stamped files. The
    names of the files will suggest the class of calculation and site for which
    the calculation was done (e.g. elev_Elkins_07_10_06_12:34:34.txt).  Averages
    are stored in files with 'avrg' embedded in the file names, instead of a
    site name.  All time series calculations are stored as separate columns in
    the same file.  The first column of each file contains the 'independent'
    quantity (e.g., MJD time, elevation, frequency) for all other columns in
    that file.  The first line in each column contains the names of the
    quantities in each column.  Thus, these files can be digested easily by
    most spreadsheet-like programs.  The directory also include column/row
    transposed versions of the output files.  The names of the transposed files
    start off with the word 'Transposed_'.  Depending upon the user's needs,
    the transposed files may prove to be useful.
 
UNITS
    Output units for the generated quantities are:
        mm                  : Precipitable Water Vapor
        Miles/Hour          : Wind speeds
        Degrees             : Wind Direction
        mBar (hPa)          : Pressure
        C                  : Air Temperature, Dew Point
        Kelvin              : System Temperature, Atmosphere Temperature, Rest
        Percent             : Humidity, Cloud Cover, Probability
        Nepers/Air Mass     : Opacity
        Nepers              : Attenuation
        kg/m^2              : Precipitation Rate
        m                   : Ceiling Height, Visibility, Height of 0C Isotherm
        W/m^2               : Irradiance
        Arc Sec             : Refraction
        Arc Sec/m           : Refraction Squint
        Air Mass/m          : Air Mass Derivative
        Unitless            : Index of refraction, K-Index, Air Mass
 
OPTIONS
    The user can use default options by not specifying any command-line
    arguments or supply values to the following arguments:
 
    -h or -help
        Brings up a help page.  If specified, all other options are ignored
    -model str
        Which model is to be processed.  Choices are NAM (3.5 days, formerly
        called ETA), GFS3 (7.5 days), or RUC (12 hrs).  (Default: NAM).
    -quiet
        Processes without generating informational messages.  The default is to
        generate messages.
    -sites list
        List of sites to process.  One or more of the following:
        Elkins, HotSprings, Lewisburg.  Default is all three.
    -PointMap
        Specifies that ground-level values for Point Map Forecasts are to be
        included.  Only used if the GroundTime or CloudsPrecipTime calculations
        have been selected.
    -CoeffModel
        ** RECOMENDED ONLY FOR ADVANCED USERS **  Indicates that the user wants
        the program to fit polynomials for Tau, Tatm, Tsys, and Rest vs.
        frequency to a set of standard frequencies and produce CoeffRslts files.
    -average
        Averages results from the selected sites.  Ignored if one site is
        selected.  The default is *not* to generate averages
    -noCaching
        Within a single run, the application uses an in-memory cache of values
        for index of refraction(P,T,dewPt), Partial Pressure of water(P,T,dewPt)
        and absorption coefficients(P,T,dewPt,freq).  The caches significantly
        reduce computation time but, since the caches use fuzzy values for P, T,
        dewPt, and freq, results may differ slightly (and negligiblly) from run
        to run.  By specifying -noCaching, the use of the internal cache is
        turned off, which should produce high accuracy and consistent results
        but at a loss in performance.  The default is to use the internal cache.
    -readCaches
        Reads in cached results from a previous run in which -writeCache was
        specified.  Ignored if -noCaching was specified.  In most cases reading
        in cached quantiies will speed up processing but at a small cost in
        accuracy. The default is not to read
    -writeCaches
        ** RECOMENDED ONLY FOR ADVANCED USERS **  Writes out internal cached
        quantities for use by future runs.  Ignored if -noCaching is specified.
        Must have write permissions to /users/rmaddale/Weather for this to work.
        The default is not to write
    -whichOpacities list
        List of opacities that are to be used in the model.  The types are:
            Hydrosols : Water droplets (clouds, fog)
            H2OCont : Water continuum
            H2OLine : Water lines
            Dry : Dry air
            O2 : Oxygen lines
        The default is all opacity types.
    -calculate list
        The list of calculations that are to be performed.
 
        If unspecified, will use: TsysTime TsysElev TsysFreq RestTime RestElev
        RestFreq OpacityTime OpacityFreq TatmTime TatmFreq RefracTime
        RefracHeight RefracDiffsTime GroundTime CloudsPrecipTime
 
        There are over 20 types of calculations that fall into various classes:
 
        Time Series:
            GroundTime : Ground values for temperature, wind speed, wind
                direction, atmodpheric pressure, temperature, dew point, and
                humidity between start and stop times
            CloudsPrecipTime : Values for cloud clover in the lower, middle, and
                upper atmosphere, the total cloud cover, precipitaion rates,
                type of precipitation, long and short-wave irradiance, K-Index
                between start and stop times.
            OpacityTime : Zenith opacities for the frequencies specified in
                freqList between start and stop times.
            RestTime : Relative effective system temperatures for the
                the frequencies specified in freqList between start and stop
                times for the elevTsys elevation.  Rests wil be calculated for
                frequencies below 116 GHz
            TsysTime : Atmospheric contributions to system temperature for
                the frequencies specified in freqList between start and stop
                times for the elevTsys elevation
            TatmTime : Opacity-weighted atmospheric temperature for the
                frequencies specified in freqList between start and stop times.
                The Tatm values to be used in the analysis of tippings
            RainAttenTime : Attenuation (not opacity) from rain for the
                frequencies specified in freqList between start and stop times
                 for the elevTsys elevation
            RefracTime, LiebeRefracTime : Various refraction models and
                quantitiesbetween start and stop times for the elevRefracAirMass
                elevation.
            RefracDiffsTime, LiebeRefracDiffsTime : Comparison between various
                refraction models between start and stop times for the
                elevRefracAirMass elevation.
            AirMassTime : Various air mass models and quantities between start
                and stop times for the elevRefracAirMass elevation
 
        Frequency Series:
            OpacityFreq : Zenith Opacities between start and stop frequencies
                for the desired date and time
            TsysFreq : Atmospheric contributions to system temperature between
                start and stop frequencies for the desired date and time for the
                elevTsys elevation
            RestFreq : Relative effective system temperatures between start and
                stop frequencies for the desired date and time for the elevTsys
                elevation.  Will be calculated for frequencies below 116 GHz.
            TatmFreq : Opacity-weighted atmospheric temperature between start
                and stop frequencies for the desired date and time
            RainAttenFreq : Attenuation (not opacity and in Nepers) from rain
                between the specified frequencies for the desired date and time
                and elevTsys elevation
            LiebeRefracFreq : Liebe's model for refraction between start and
                stop frequencies for the desired date and time for the
                elevRefracAirMass elevation.
 
        Elevation Series:
            TsysElev : Atmospheric contributions to system temperature between
                start and stop elevations for the frequencies specified in
                freqList for the desired date and time
            RestElev : Relative effective system temperatures between start and
                stop elevations for the frequencies specified in freqList.
                Rests wil be calculated for frequencies below 116 GHz.
            RefracElev, LiebeRefracElev : Various refraction models and
                quantities between start and stop elevations
            RefracDiffsElev, LiebeRefracDiffsElev : Comparison between various
                refraction models between start and stop elevations
            AirMassElev : Various air mass models and quantities between start
                and stop elevations  for the desired date and time
            RainAttenElev : Attenuation (not opacity) from rain between the
                 start and stop elevations for the desired date and time.
            AirMassDiffsElev : Comparison between various refraction models
                between start and stop elevations for the desired date and time.
 
        Miscellaneous:
            RefracHeight, LiebeRefracHeight : Various refraction quantities as a
                function of height above the selected sites
            RefracDumpData : Refraction quantities and models for various
                internally-selected elevations between start and stop times
 
    -hghtLimit meters
        Allows one to limit the maximum elevation to which Tau, Tatm, and Tsys
        calculations will be performed.  Setting hghtLimit will educe the
        accuracy of the results but will improve performance.  For example,
        setting to  17000 will introduce a few percent inaccuracy but will
        speed up  the opacity-like calculations by 20%.  Default is to use all
        heights.
    -skipO2
        A flag which, if specified, will ignore all calculations of opacity,
        Tsys,or RESTs that fall near the two major O2 lines (between > 52
        and 68 GHz and between 171 and 197 GHz) covered by this modelling.
    -freqList list
        List of frequencies in GHz.  Must be >= 1 and <= 235 GHz.  Used only if
        the following calculations are performed: OpacityTime, TsysTime,
        RestTime, TatmTime, TsysElev, or RestElev.
        Default is: 6 8 10 12 14 16 18 20 22 24 27 30 33 36 39 42 45 48 68 74 80
        86 92 98 104 110 116 GHz
    -elevTsys elevation
        Elevation in degrees.  Must be >= 0 and <= 90.  Used only if the
        following calculations are performed: TsysTime, RestTime,
        TsysFreq, or RestFreq.  Default is 30 degrees.
    -elevRefracAirMass  elevation
        Elevation in degrees.  Must be >= 0 and <= 90.  Used only if the
        following calculations are performed: AirMassTime or RefracTime
        TsysFreq, and RestFreq.  Default is 10 degrees.
    -desiredTime timeDate
        A date/time of the form "MM/DD/YYYY H:M:S" (with quotation marks). 
        Will be able to handle most varients of this format.  Used as the time
        at which any of the Frequency or Elevation Series, or RefracHeight
        calculations are performed.  Default is the current time.  Ignored if
        -mimicHistorical isspecified
    -startTime timeDate
    -stopTime timeDate
        UT Date and times of the form "MM/DD/YYYY H:M:S" (with quotation
        marks) or most standard varients of this format.  Used as the start and
        stop times by all of the Time Series and RefracDumpData calculations. 
        Defaults are 12 hrs before desired time and 12, 85 or 180 hrs after
        desiredTime for, respecively, the RUC, NAM or GFS3 models.  If
        -mimicHistorical is specified then startTime must be specified and
        stopTime will be ingorned.
    -incrTime numHrs
        Time increment in hrs between calculations.  Used by all of the
        Time Series and RefracDumpData calculations.  Default is 1 hr for the
        NAM and RUC models, and 3 hrs for GFS model
    -startFreq freq
    -stopFreq freq
    -incrFreq freq
        Start, stop and frequency steps in GHz.  Must be >= 1 and <= 235 GHz.
        Used by all of the Frequency Series calculations.  Default values are
        6 to 116 GHz in steps of 2 GHz.
    -startElev elev
    -stopElev elev
    -incrElev elev
        Start, stop and frequency elevations in Degrees  Must be >= 0 and <= 90.
        Used by all of the Elevation Series calculations.  Default values are 5
        to 90 degrees in steps of 5 degrees.
    -mimicHistorical
        ** RECOMENDED ONLY FOR ADVANCED USERS ** A flag which, if specified,
        will indicate that one wants to use the database *as it was* at the
        specified start time.  That is, all archive files stored *after* the
        specified start time are ignored.  A start time must be specified.  Any
        specified stop and desiredTime will be ignored.  Instead, desiredTime is
        set to startTime plus half the maximum time span of a single archive
        file for the specified model
    -startOffset offNum
    -stopOffset offNum
        ** RECOMENDED ONLY FOR ADVANCED USERS **  Used to specify explicitly
        which time slots are to be processed within each raw data file.  Units
        are the time steps within each type model's file.
    -fastCalc
        A flag which, if set, tells the prograam to use the faster but rougher
        Lehto model for opacities instead of the more accurate Liebe model
    -saveAll
        A flag, which if specified, will save all possible columns for the
        desired calculations, instead of those the programmer has deemed most
        interesting