NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > PlanOfRecordC32006 > ModificationRequest14C306

Changes | Index | Contents | Search | Statistics | Go

Add LST Capabilities to Scheduling Blocks

Modification Request #14 (C3 2006)

• 1. Introduction
• 2. Background
• 3. Requirements
  • New Capabilities
  • New Constructs Described as User Documentation
    • In Observing API Building Blocks Section
    • In Observing Directives Section
    • In GBT Scan Types Section
  • Conditions and Exceptions
• 4. Design
• 5. Deployment Checklist
• 6. Out of Scope
• 7. Test Plan
• Signatures
• CCC Discussion Area

1. Introduction

Observers need the ability to write scheduling blocks with behavior that is conditional upon current conditions, especially the position of the earth relative to the sources to be observed. This MR addresses rudimentary aspects of this need by providing scheduling block facilities for handling LST and the rising and setting of sources.

2. Background

Currently, scheduling blocks handle time as Ygor does, i.e., times may only be represented by UTC constants. Also, turtle provides no error checking of the user-specified times, e.g., if the user requests a scan start time which is in the past, that time is directly passed on to the telescope control system which does not detect the error until the beginning of the scan; this in turn causes the subscan to fail with an abort. A long-term goal of scheduling blocks is to provide observers with enough flexibility that they can write scheduling blocks which are capable of anticipating possible failure conditions and respond accordingly. In addition, if turtle is ever to be used as a batch processing system, i.e., the scheduling blocks are initiated by an operator in the order and time s/he determines, then it will have to be sensitive to the current position of the earth, i.e., the current LST.

3. Requirements

New Capabilities

• Source-dependent times may be specified for scan start and stop times, i.e., "at source rise" and "at source set".
• LST times may be specified for scan start and stop times.
• The current time may be obtained in either UTC or LST.
• LST Start and Stop times are "dateless," i.e., time only, no date.
• UT start and stop times may be either "dateless" or absolute (i.e, date+time).

New Constructs Described as User Documentation

In Observing API Building Blocks Section

• Horizon(elevation) - Observing scripts allow an observer to specify a definition of the horizon, and use this definition to begin an observation when an object rises and/or end the observation when it sets. The Horizon object may be used to obtain the initial time that a given source is above the horizon including approximate atmosphere refraction in elevation where "above" may be defined when the object is created, e.g., horizon = Horizon(10.0) defines a horizon that is 10 degrees above zero degrees encoder elevation. If no argument is given to Horizon, it will assume a default of 5.25 degrees. The specified horizon in degrees is accessible by calling horizon.PhysicalHorizon() and the computed refraction in degrees by calling horizon.RefractionCorrection(). To dynamically control observing, any Horizon object may be substitued as a start or stop time in scan types. The rise and set times for start and stop times for any sky location in spherical coordinates may be obtained as a UTC time and date (mx.DateTime) by calling horizon.GetRise(location) which returns the nearest rise time and horizon.GetSet(location) which returns the next set time, where location is a Catalog source name or a Location source specified in a spherical coordinate system. For example, to display the rise time of "0616-1041" (the previous rise time if the source is above the horizon or the next rise time if the source is below the horizon): print Horizon().GetRise("0616-1041") Circumpolar locations or sources have the following return values:

• time may be represented as either a sexagesimal string or a mxDateTime object. (Note, one must access the DateTime module directly from an observation script to generate time objects, i.e., from mx import DateTime).
  • Types:
    • absolute or dated times - specify both time of day and date, and may be represented by either a sexagesimal string, i.e., "yyyy-mm-dd hh:mm:ss" or a DateTime object.
    • relative or dateless times - specify the time of day for "today" where times more than 10 minutes in the past are treated as in the future, and may be represented by either a sexagesimal string, i.e., "hh:mm:ss" or a DateTimeDelta object.
  • UTC - may be either absolute or relative. The sexagesimal representation may include a "UTC" suffix. Note that mxDateTime objects are always UTC.
  • LST - may only be relative. The sexagesimal representation must include a "LST" suffix.
  • Examples are:
    • "2006-03-22 15:34:10" - absolute time in UTC represented by a string
    • DateTime.TimeDelta(12, 0, 0) - relative time in UTC as a mxDateTime object
    • "2006/03/22 15:34:10 UTC" - absolute time in UTC represented by a string
    • "22:15:48 LST" - relative time in LST as a string
    • DateTime.DateTime(2006, 1, 21, 3, 45, 0) - absolute time in UTC as a mxDateTime object

In Observing Directives Section

• GetUTC(), GetLST(). These directives return a float representing the current time in UTC or LST as hours since midnight, e.g.,

    while GetLST() < 13.5:
        PointMap("1153+1107", 
                 Offset("B1950", 1.50, 0.00, cosv=False),
                 Offset("B1950", 0.00, 1.50, cosv=False),
                 Offset("B1950", 0.50, 0.00, cosv=False),
                 Offset("B1950", 0.00, 0.50, cosv=False),
                 2.0)

• Now(). This directive returns the current time as a UTC time and date (mx.DateTime), e.g.,

    h = Horizon(15.0)
    while Now() < h.GetSet("1153+1107"):
        PointMap("1153+1107", 
                 Offset("B1950", 1.50, 0.00, cosv=False),
                 Offset("B1950", 0.00, 1.50, cosv=False),
                 Offset("B1950", 0.50, 0.00, cosv=False),
                 Offset("B1950", 0.00, 0.50, cosv=False),
                 2.0)

• WaitFor(time). This directive pauses the scheduling block until the specified time is reached, e.g., WaitFor("15:13:00 LST"). The expected wait time is printed in the observation log including a warning if the wait is longer than 10 minutes. Using a Horizon object (which is represented as a previously created Horizon object, h, in the following examples), this directive can be used to wait for a source to rise, WaitFor(h.GetRise("1532+3421")), or to set, WaitFor(h.GetSet("sun")). WaitFor will return immediately if the source has already risen. If WaitFor's argument is None then it aborts with an error message to the observation log. This can occur when Horizon='s methods =GetRise() or GetSet() detect an event which will never occur, i.e., the rise time for a source that never rises or the set time for a source that never sets. While WaitFor is in the "wait" state, it does not prevent the user from aborting a script, however if the user chooses to continue once the abort is detected, then the WaitFor abandons the wait and returns immediately.

In GBT Scan Types Section

The current definitions of the scan type parameters affecting timing are:

• startTime is a time string with the following format: "hh:mm:ss". It allows the observer to specify a start time for the scan.
• stopTime is a time string with the following format: "hh:mm:ss". It allows the observer to specify a stop time for the scan.
• scanDuration is a float. It specifies the length of each subscan in seconds.

The new definitions are:

• startTime specifies when the scan begins. If the start time is in the past then the scan starts as soon as possilble with a message sent to the scan log. If the start time plus the scan duration is in the past, then the scan is skipped with a message to the observation log. The value may be:
  • a time Note, if startTime is more than a ten minutes in the future then a message is sent to the observation log.
  • a Horizon When a Horizon object is used, the start time is implicitly computed, e.g., Track("3C247", None, 120.0, startTime=Horizon()) If the source never rises then the scan is skipped and if the source never sets then the scan is started immediately. In either case a message is sent to the observation log.
• stopTime specifies when the scan completes. If the stop time is in the past then the scan is skipped with a message to the observation log. The value may be:
  • a time
  • a Horizon When a Horizon object is used, the stop time is implicitly computed, e.g., a complete scheduling block for tracking VirgoA from rise until set and using a horizon of 20 degrees would be: Catalog("fluxcal"); horizon = Horizon(20.0); Track("VirgoA", None, startTime=horizon, stopTime=horizon) If the source never sets, then the scan stop time is set to 12 hours from the current time.
• scanDuration specifies the length of the scan. If the resulting stop time has passed, then the scan is skipped and a message is sent to the observation log. The value is a float representing seconds.

Conditions and Exceptions

• A "dateless" time, whether UTC or LST, if more than 10 minutes in the past, is regarded as being in the future.
• If the WaitFor time is in the past, WaitFor returns immediately.
• If the WaitFor time is more than 10 minutes in the future, it waits, but issues a warning message.
• If a startTime (whether a rise time or explicitly given) is in the past, the current time is used and the Scan Type runs immediately.
• If a startTime is more than 10 minutes in the future, the Scan Type waits, but issues a warning message.
• If a stopTime is in the past, the Scan Type ends immediately.
• If a source is circumpolar, i.e, it never sets below the specified horizon, then the rise time is the current time (the Scan Type starts immediately), and the set time is 12 hours in the future.
• If a source never rises, then the rise time is None, WaitFor returns immediately with an error message. A scan type given a rising or setting for a source that never rises will return immediately with an error message.

4. Design

All changes are limited to the Observation Management System (i.e. turtle). No changes to the M&C Managers are necessary.

• collate the handling of time representations into one module called TimeAgent
• user.Horizon will be added as support class like Offset, Location, and Catalog
• user.Scan.Normalize will be enhanced to handle Horizon objects as well as absolute DateTime objects and strings
• scan types - the user's specified times vs the current time will be checked in user.Scan.CanRunScanNow
• absolute times:
  • user.Scan.Normalize() will guarantee that start and stop times are DateTime objects or None
  • user.Telescope.ComputeDuration() will be modified to use absolute times
• date plus time of day strings with optional suffix will be handled in user.Scan.Normalize() along with time of day strings
• calculations - The calculation of rise time and set time takes into account the effect of atmospheric refraction, using an approximate formula from Ron that does not require knowing the temperature or weather conditions. See horizonCodePrototypes for examples of a)calculating the rise and set times, b)refraction formula, c)calculation of sidereal time, and d)conversions to apparent coordinates, using the routines in SLAlib.
• GetUTC and GetLST will be implemented in user like GetCurrentLocation and other Observing Directives.
• WaitFor is implemented such that the "wait" loop is in ygor.Telescope so it may monitor the abort flag much like the TakeSpigotData Observing Directive.
• Handle solar system objects in Horizon. (tabled for this release)

5. Deployment Checklist

Standard sparrow build and install procedures along with copying the user documentation in this MR to the wiki documentations as titled in the subsections above (Building Blocks, Observing Directives, and Scan Types) should be sufficient. A small overview of typical scheduling blocks which use LST conditionals will be added by the sponsor to ObservingTools after some experience is gained working with these new constructs.

Because the new observing directives will encourage users to create loops dependent on time, e.g., WaitFor?(), it has become more likely that they will generate observing scripts that will not validate because of infinite loops or skip key sections. Until a solution is determined, the documentation must have a caveat in the Observing Directives section explaining the problem and providing work arounds.

6. Out of Scope

Scan type do not attempt to determine if a given start time in the future is attainable, i.e., can the antenna slew to position before the requested start time. Astrid uses Ygor's "old college try" approach, i.e., when given a specific start time it starts the scan at the time regardless if on source or not. A future MR needs to address this by having the scan types skip scans or readjust the start time for too-early requested start times by computing a coarse estimate of the requisite slew time.

Need to develope a means of having observing directives and/or time-dependent code from causing observing scripts from failing validation.

7. Test Plan

As usual unit tests will be used to test as much as possible.

On the simulator and telescope:

• Write exhaustive unit tests for the generic time utility functins in new module, TimeAgent.
• Horizon per se will be tested through its methods GetRise() and GetSet(). The tests will be run both under Astrid and as a set of unit tests. The methods will take an additional undocumented defaulted argument which specifies the current time which will allow the writing of repeatable unit tests. Rise and set time for both spherical objects and planets will be tested as well as the special source characteristics listed in the following table. In the test table t₀ is the current time, t_s+ is the next set time, t_r+ is the next rise time, t_s- is the last set time, and t_r- is the last rise time for the source S.

source characteristic	GetRise(S, t0)	GetSet(S, t0)
risen	tr-	ts+
set	tr+	ts+
never sets	t0	None
never rises	None	t0

• Test Horizon using Track() for all conditions in the above table for both start and stop times. Exercise the generation of all messages.
• Test GetUTC and GetLST by simply printing the return values of the directives in Astrid.
• Test the WaitFor directive by entering LST and UTC times just prior midnight and after midnight; and which cause the wait to cross midnight. Repeat the tests for both relative and absolute representations of time. Run one test in conjunction with a Horizon method. Exercise the generation of all messages.
• Test the Track scan type for both relative LST/UTC and absolute UTC time representations as both string and mx.DateTime objects as values for the startTime parameter value. Exercise the generation of all messages.

Signatures

APPROVED: I acknowledge that my request is fully contained in this MR, and if the SDD delivers exactly what I specified, I will be happy.

ACCEPTED: I acknowledge that I have validated the completed code according to the acceptance tests, and I am happy with the results.

Written	- MarkClark - 18 May 2006
Checked	- AmyShelton - 18 May 2006
Approved by Sponsor	- FrankGhigo - 18 May 2006
Approved by CCC	- RichardPrestage - 07 June 2006
Accepted/Delivered by Sponsor	- FrankGhigo - 20 June 2006

Symbols:

• Use %X% if MR is not complete (will display )
• Use %Y% if MR iscomplete (will display )

CCC Discussion Area

Attachment:	Action:	Size:	Date:	Who:	Comment:
mxDateTime.html	action	109191	26 Apr 2006 - 14:14	MarkClark	mx.DateTime