NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > SoftwareReportCentral_ReleaseNotes > ObservingAPIReleaseNotes_6_4

Changes | Index | Contents | Search | Statistics | Go

Release Notes for Observing API (turtle) Version 6.4 - Released on Wednesday, June 28, 2006

• Add LST Capabilities to Scheduling Blocks
  • Additions to the Observing API Building Blocks
  • Additions to the Observing Directives
  • Modifications to the GBT Scan Types
  • Conditions and Exceptions

Add LST Capabilities to Scheduling Blocks

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. We have added rudimentary aspects of this need by providing scheduling block facilities for handling LST and the rising and setting of sources.

The following are a list of requirements satisfied by this change:

• 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).

Additions to the Observing API Building Blocks

• 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:

circumpolar	GetRise()	GetSet()
northern (never sets)	current time	None
southern (never rises)	None	current time

• 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

Additions to the Observing Directives

• 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.

Modifications to the GBT Scan Types

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.