NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > ObservingAPIBeta > ObservingAPIBuildingBlocks

Changes | Index | Contents | Search | Statistics | Go

Observing API Building Blocks

The purpose of Turtle to to provide a series of building blocks that observers may utilize to create their own observation procedures; these building blocks can then be used to create complex movements of the beam across the sky. Turtle will also provide a pre-defined suite of commonly used procedures created by on-site astronomers for observers, which in turn may also be used as building blocks to create even more complex beam movements. Observers who only use the pre-defined procedures will probably not find this page useful, since they only deal with the procedures at a higher level (in a scheduling block). The suite of predefined procedures is enumerated later in this page as observing cases.

• Building Blocks
• Observing API Source Code for Selected Scan Types
  • Slew
  • Track
  • Peak
  • On-Off
  • Nod

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, e.g., Track. 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:

      Note that Horizon only works for objects defined in catalogs
      with spherical coordinates.  Planets and ephemeris tables will not work.

• Location - A Location is used to represent a particular location on the sky. Locations can be specified in the following coordinate modes: "J2000", "B1950", "RaDecOfDate", "HaDec", "ApparentRaDec", "Galactic", "AzEl", and "Encoder." A Location is specified by two values, the meanings of which are dependent on the coordinate mode chosen. E.g. For J2000, the two values are time and degrees. Offsets and Locations may be added together. Here is an example of how to specify a Location:
  location = Location("J2000", "16:30:00", "47:23:00")
• Offset - An Offset is a displacement from a given Location. Offsets can be specified in the following coordinate modes: "J2000", "B1950", "RaDecOfDate", "HaDec", "ApparentRaDec", "Galactic", "AzEl", and "Encoder." An Offset is specified by two values (generically called h and v), the meanings of which are dependent on the coordinate mode chosen. E.g. For J2000, the two values are right acsension (h) and declination (v). Values can be entered in sexigesimal notation or decimal degrees (or a combination). Also, the user can specify whether cosV should be taken into account for the Offset; True = cosv is applied (i.e. h is divided by the cosine of v), False = cosv not applied. The default value is True. Offsets may be added together and may also be added to Locations. Here is an example of how to specify an Offset:
  offset = Offset("J2000", "00:30:00", "05:00:00", cosv = False)
• Beam - A Beam is a software representation of the beam on the sky. To perform an observation, the beam is moved around on the sky in a particular pattern. Patterns can be created using three primitive commands: MoveTo, Move, FocusTo, Focus, and GetStartLocation. A Beam uses an Antenna object to send movement commands to the Antenna Manager and it also requires a name. Here is an example of how to specify a Beam:
  beam = Beam(Antenna(), "1")
  • MoveTo - This primitive command moves the beam to a specific Location. Here is how to move the example Beam to the example Location:
    beam.MoveTo(location)
  • Move - This primitive command moves the beam to the specified Offset. The Offset is in relation to a previously specified Location. Therefore, a MoveTo must be performed at some point in an observation before a Move. Here is how to move the example Beam to the example Offset:
    beam.Move(offset)
  • FocusTo - This primitive command moves the subreflector (for Gregorian receivers) or primary (for Prime Focus receivers) to a specified position. Here is how to move the example Beam to a specified position:
    beam.FocusTo(-100.0)
  • Focus - This primitive command moves the beam to the specified offset (note that this offset is a float rather than an Offset). The offset is in relation to a previously specified position. Therefore, a FocusTo must be performed at some point in a scan before a Focus. Here is how to move the example Beam to an example offset position:
    beam.Focus(200.0)
• Receiver - A Receiver is the software representation of the physical receiver. Receivers have Beams.
• Scan - A Scan is the software mechanism for communication with the M&C system. The scan class has the following methods:
  • AddAnnotation - Adds a keyword/value pair to the GO FITS file.
    AddAnnotation("MYKEYWRD", "value", "optional comment")
  • Break - Causes the scheduling block to pause temporarily.
    Break("add message here (if desired) to override default message")
  • Balance - Balances the IF system. The method used to balance the IF system is dependent on configuration. If you wish to override the default balance scheme by using one of the following strings: "IFRack", "Spectrometer", "SpectralProcessor".
    Balance() or Balance("IFRack")
  • Comment - Prints a comment to the monitor tab of the Turtle GUI.
    Comment("Howdy")
  • Execute - Sends a command to the telescope.
  • GetValue - Retrieves a parameter value from a particular manager.
    value = GetValue("ScanCoordinator", "source")
  • Prepare - Sends an activate to the M&C system.
  • RemoveAnnotation - Removes a previously specified annotation from being written to the next GO FITS file.
    RemoveAnnotation("MYKEYWRD")
  • SetDuration - Set the scan length (in seconds) for the next scan.
    SetDuration(60.0)
  • SetValues - Sets a parameter value for a particular manager.
    SetValues("ScanCoordinator"), {"source": "mySourceName", "scanId" : "myScanDescription"})
  • Start - Start taking data; starts a scan.
  • Stop - Stop taking data; stops a scan.
• Catalog - A Catalog represents a set of points or locii on the sky in spherical, Ephemeris, NNTLE, or obit formats accessible by a name. The actual catalog representation may be specified by system catalog name, a path to a catalog file, or directly in-line as part of the scheduling block. All of the pre-defined procedures accept any name from any Catalog declared in a scheduling block to specify a location. Planet names are pre-defined in an internal catalog.

• 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

Observing API Source Code for Selected Scan Types

The following examples show how the Observing API Building Blocks have been used to describe patterns of antenna motion which are commonly needed by observers. These scan types can be called directly in an observing script which is part of a Scheduling Block. Note: The creation of receiver and scan objects is omitted from the examples in order to focus attention on antenna movement rather than coding details.

Slew

The "Slew" observing procedure simply moves the GBT to a Location on the sky. The "Slew" observing procedure is composed of one building block - a MoveTo. Here is how a "Slew" might be implemented using the building blocks mentioned above:

beam     = receiver.GetBeam("1")
location = Location("J2000", "15:30:00", 14.0)

scan.SetDuration(60.0)

beam.MoveTo(location)

Track

The "Track" observing procedure causes the GBT to track a Location on the sky. The "Track" observing procedure is composed of two building blocks - a MoveTo a Location and a Move to an Offset. Here is how a "Track" might be implemented using the building blocks mentioned above:

beam     = receiver.GetBeam("1")
location = Location("J2000", "15:30:00", 14.0)
offset   = Offset("J2000", "00:15:00", 16.0)

scan.SetDuration(60.0)

scan.AddAnnotation("PROCNAME", "Track")
scan.AddAnnotation("PROCTYPE", "SIMPLE")
scan.AddAnnotation("PROCSIZE", 1)

beam.MoveTo(location)

scan.Comment("Track: Subscan 1 of 1\n")
scan.AddAnnotation("PROCSEQN", 1)

scan.Start()
beam.Move(offset)
scan.Stop()

In the implementation of "Track," an Offset does not have to be specified. This value defaults to None if an Offset is not specified.

Peak

The Peak procedure sweeps through the specified sky location in the four cardinal directions. Its primary use is to determine pointing offsets for use in subsequent procedures.

beam     = receiver.GetBeam("1")
location = Location("J2000", "01:37:41.30", "+33:09:35.4")
hOffset  = Offset("Encoder", "90:00", 0)
vOffset  = Offset("Encoder", 0, "90:00")

scan.SetDuration(60.0)

scan.AddAnnotation("PROCNAME", "Track")
scan.AddAnnotation("PROCTYPE", "SIMPLE")
scan.AddAnnotation("PROCSIZE", 4)

beam.MoveTo(location)
beam.Move(-hOffset/2)

scan.Comment("Peak: Subscan 1 of 4\n")
scan.AddAnnotation("PROCSEQN", 1)

scan.Start()
beam.Move(hOffset)
scan.Stop()

scan.Comment("Peak: Subscan 2 of 4\n")
scan.AddAnnotation("PROCSEQN", 2)

scan.Start()
beam.Move(-hOffset)
scan.Stop()

beam.MoveTo(self.location)
beam.Move(-vOffset/2)

scan.Comment("Peak: Subscan 3 of 4\n")
scan.AddAnnotation("PROCSEQN", 3)

scan.Start()
beam.Move(vOffset)
scan.Stop()

scan.Comment("Peak: Subscan 4 of 4\n")
scan.AddAnnotation("PROCSEQN", 4)

scan.Start()
beam.Move(-vOffset)
scan.Stop()

On-Off

The "On-Off" observing procedure can be described using two "Track" procedures - one "Track" for Off and one "Track" for On. Here is how "On-Off" might be implemented using the building blocks mentioned above:

beam     = receiver.GetBeam("1")
location = Location("J2000", "15:30:00", 14.0)

scan.SetDuration(60.0)

scan.AddAnnotation("PROCNAME", "OnOff")
scan.AddAnnotation("PROCTYPE", "SIMPLE")
scan.AddAnnotation("PROCSIZE", 2)

beam.MoveTo(self.location)

# On source
scan.Comment("OnOff: Subscan 1 of 2\n")
scan.AddAnnotation("PROCSEQN", 1)

scan.Start()
beam.Move(None)
scan.Stop()

beam.Move(self.offset)

# Off source
scan.Comment("OnOff: Subscan 2 of 2\n")
scan.AddAnnotation("PROCSEQN", 2)

scan.Start()
beam.Move(None)
scan.Stop()

Nod

The "Nod" observing procedure can be described using two "Track" procedures. Here is how "Nod" might be implemented using the building blocks mentioned above:

beam1    = receiver.GetBeam("1")
beam2    = receiver.GetBeam("2")
location = Location("J2000", "15:30:00", 14.0)

scan.SetDuration(60.0)

scan.AddAnnotation("PROCNAME", "Nod")
scan.AddAnnotation("PROCTYPE", "SIMPLE")
scan.AddAnnotation("PROCSIZE", 2)

# Track Beam 1
beam1.MoveTo(location)

scan.Comment("Nod: Subscan 1 of 2\n")
scan.AddAnnotation("PROCSEQN", 1)

scan.Start()
beam1.Move()
scan.Stop()

# Track Beam 2
beam2.MoveTo(location)

scan.Comment("Nod: Subscan 2 of 2\n")
scan.AddAnnotation("PROCSEQN", 2)

scan.Start()
beam2.Move()
scan.Stop()