Instructions for ~rmaddale/bin/MappingCalculator.tclsh

Ronald J Maddalena
December 22, 2014

The script also has a web interface, though with fewer options and tailored just for the GBT.

MappingCalculator.tclsh -- Calculates the time needed to map an area based
    on the integration time per beam area (e.g., the results from sensitivity
    calculations, and the area to be mapped.  Provides example ASTRID commands
    as well as other mapping parameters.  Supports the typical mapping commands
    for OTF rectangular maps, OTF Daisy maps, and point rectangular maps.  Does
    not include the observing time or overhead if you use the Astrid observing
    procedures of PointMapWithReference, RALongtMapWithReference, or
    DecLatMapWithReference.

 SYNOPSIS
     MappingCalculator.tclsh [-h | -help] [-freqGhz f] [-tPerBeam tsec]
            [-xSizeDeg dx][-ySizeDeg dy] [-tMinSample tsec] [-fRowColPetal f]
            [-fSample f] [-DishDiamMtr D] [-apEff a] [-slewMaxDegPerMin sr]
            [-tOverheadPerRowCol tsec] [-tResolution tsec] [-useOmegaA]
            [-maxNumAccelPerMin n]

 DESCRIPTION
     Unlike the standard mapping calculator, which asks for integration time
     per pixel, here one supplies the integration per beam area (i.e., the
     results of any sensitivity calculation) without the need to calculate
     pixels per beam area.  In most cases, one need only supply values for
     a few mandatory parameters to get reasonable results.
    
ALGORITHM DETAILS
     The algorithms makes sure that the calculated time per sample is an
     integer multiple of the backends time resolution and has a value greater 
     than the backend's minimum sampling time.  The calculated slew rate is kept
     below the telescope's maximum.  The time per row will always be an integer
     multiple of the sample time.  And, the number of rows or petals in the map
     will be integer.  The caculator always rounds up so that one will always
     get at least the desired time per beam area.
    
     Because of these restriction in possible sample and slew rates, the actual
     time per beam area will be larger than that specified but that value will
     always be as close as it possible to the user's input value.  The user
     should be aware that THERE ARE A LARGE NUMBER OF SITUATIONS WHEN THE
     ACTUAL VALUE FOR TIME PER BEAM WILL BE MUCH LARGER THAN THE DESIRED VALUE.
     In these cases, the only recourse is to find a backend that samples
     faster or a telescope that slews faster.
    
     Note: For mapType of OTFRect the calculator provides separate answers for
     RALongMap and the DecLatMap as the overhead, row spacing, etc will be
     different for the two styles of map.

MANDATORY PARAMTERS
    -freqGhz f       Observing frequency in GHz.

    -tPerBeam        Integration time per beam area, in seconds.

MANDATORY PARAMETERS DEPENDENT UPON -mapType
    -xSizeDeg dx     Map size in the RA/Long direction in degrees.  Ignored
                     if -mapType is OTFDaisy.

    -ySizeDeg dy     Map size in the Dec/Lat direction in degrees.  Ignored
                     if -mapType is OTFDaisy.

    -mapRadiusDeg d  Map radius in degrees.  Only used if mapType is OTFDaisy.

 OPTIONAL PARAMETERS
    The user can supply the following optional arguments:
 
    -h or -help      Brings up a help page.  If specified, all other
                     options and operands are ignored

    -mapType str     The type of map.  Either:
                        OTFRect   -- on-the-fly rectangular area (default)
                        OTFDaisy  -- on-the-fly daisy pattern, or
                        PointRect -- pointed map of a rectanguar region.

    -DishDiamMtr D   Dish diameter in meters.  Default: 100.

    -tMinSample t    Backend's minimum sample time in seconds.  Can be zero.
                     Default: .1

    -tResolution t   Backend's sampling time resolution in seconds.  Can be
                     zero.  Default: .1

    -tOverheadPerRowCol t  Overhead in move time between row/column in a map in
                           seconds.  Default: 15, which is typical for a Point
                           or bidirectional OTF map.  Unidirectional OTF maps
                           will havea higher overhead that is dependent upon the
                           map size.  Ignored if mapType is OTFDaisy.

    -slewMaxDegPerMin r    Telescope's maximum slew rate in deg/min. 
                           Default: 18.  Ignored if mapType is PointRect

    -apEff e         Aperture efficiency.  If not supplied, the calculator will
                     use the theoretical value for a surface with an rms of 220
                     microns.  Used in the antenna theorem to derive the area of
                     the telescope's beam when -useOmegaA is specified.

    -fRowColPetal f  For maptype of OTFRect, the amount of over sampling per row
                     (for RALongMap) or columns (for DecLatMap).  For mapType of
                     PointRect the amount of over sampling per row and
                     per column.  For mapType of OTFDaisy, the oversampling in
                     the pattern's petals.  If > 1, you will be oversampling.
                     Default: 1 (i.e., critical sampling). 

    -fSample f       The amount of over sampling in the direction of the OTF
                     slew.  We usually recommend a value of 2, the default.
                     Ignored if mapType is PointRect.
   
    -useOmegaA       A flag, which is specified, tells the calulator to use
                     the beam solid angle (from the antenna theorem) instead of
                     the default of the main beam solid angle.

    -Te n            The feed illumination taper in dB.  Only used if -useOmegaA
                     is *not* specified.  The default is 13 dB (the sign of
                     the input value is ignored).  Accuracy will degrade if
                     > 40 dB.

    -maxNumAccelPerMin n   
                     The maximum number of accelerations per minute
                     above which a warning message will be generated.  Warns
                     the user if they will be putting the telescope through
                     what would be considered excess fatique.  Default = 2.

RESULTS
    The calculator first displays all the user input values, followed by a table
    of general results, then a table of results specific for the desired
    mapType, and, finally, example ASTRID and Config Tool entries that would
    execute the desired map.