NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > ObservingTools > ObservingToolsUsage

Changes | Index | Contents | Search | Statistics | Go

Using GBT Observing Tools

• A. Write your observing script.
  • Step 1: Specify Your Sources.
  • Step 2: Select (or Define) Your Configuration.
  • Step 3: Describe Your Observation.
• B. Run your observing script.
  • Step 1: Setting Up Permissions in the Gateway.
  • Step 2: Launch Astrid.
  • Step 3: Load your Scheduling Blocks
  • Step 4: Execute Your Scheduling Block on the Telescope
    • Monitoring Your Scheduling Block
    • Managing the Execution of Your Scheduling Block

Quick Links: Source Catalogs, ScanTypes, ObservingDirectives, Configuration Cases

You can access the Observing Management system via the Astrid application. To start Astrid, simply type astrid in a window on any Linux machine. If you are the currently scheduled observer, then you should run from one of the machines in the GBT Control Room.

A. Write your observing script.

Observing scripts can be written in Astrid ("Observation Management" Edit tab), which contains a simple text editor reminiscent of Notepad, or your favorite text editor (e.g. emacs). If you choose to write your script outside of Astrid, you will still need to use the "Observation Management" tab in Astrid to upload it into the database (via the Import facility).

A screenshot of the Edit tab can be found here.

Prior to your telescope time, you should store all of your Scheduling Blocks in the Observation Management Database. All Scheduling Blocks must pass a syntactic validation process before they are stored to this database, so storing your blocks to the database ahead of your on-telescope time will help you avoid losing time due to syntax problems in what you have written. Additionally, make sure your project ID is valid and entered into the Observation Management Database. Nicole, Amy, or the operators can check on this for you, and/or make the appropriate entries into the database.

The Edit tab within the "Observation Management" application component allows you to manage the Scheduling Blocks associated with your project. To begin using the Edit tab, select your project from the drop-down list. The drop-down list will allow you to type your project name rather than selecting it via the mouse (if you so desire). When typing a project name, the application will try to auto-match what you are typing to an existing project. Once a project is selected, the Scheduling Block list (located beneath the project id widget) will be populated with every Scheduling Block associated with your project. To bring a Scheduling Block's observing script into the editor, simply click on the Scheduling Block's name within the Scheduling Block list. If the project does not have any Scheduling Blocks, you may create a new Scheduling Block by simply typing your observing script into the editor (or importing it from a file via the Import from File button located beneath the editor) and clicking on the Save to Database button. Once saved, the new Scheduling Block will appear in the Scheduling Block list.

Other operations are also supported for Scheduling Blocks. You may delete a Scheduling Block from the database via the Delete from Database buttons located below the editor or by right-clicking on the Scheduling Block's name in the Scheduling Block list. The functionality of the Delete from Database button is also mirrored on the tool bar and in the File drop-down menu. Additionally, you may rename or copy a Scheduling Block by right-clicking on the Scheduling Block's name in the Scheduling Block list.

If you wish to save a Scheduling Block from the database to hard disk, you can use the Export to File button located beneath the editor. The functionality of this button is also mirrored on the toolbar and in the File drop-down menu.

The Validate button allows the user to manually check the syntactic validity of the observing script. Astrid will automatically validate observing scripts when you save them to the database, so the button is provided for the user’s convenience. The functionality of the Validate button is also mirrored on the tool bar and in the File drop-down menu.

The following steps walk you through observing script creation.

Step 1: Specify Your Sources.

Sources are specified via catalogs either by selecting from the system catalogs in /home/astro-util/astridcats, by providing a path to your own catalog, or by defining a catalog in-line as part of the script. Source catalogs may also contain source-specific values to be set in the telescope system, e.g., radial velocity.

One may also use the system default catalog, which is specified in your observing script as: Catalog()

Step 2: Select (or Define) Your Configuration.

There are three ways to set up the system: a) use a predefined Configuration Case with or without edits, b) define your configuration metakeywords directly within your observing script, or c) include a configuration script that you have prepared previously.

a) Using a predefined Configuration Case with or without edits.

You can refer to any of the predefined Configuration Cases by name (listed in the "Project Type" column on that page). This is case sensitive. For example, for Case 20, the complete configuration script can be referred to in your observing script as:

Configure("High redshift CO")

This configures two beams, with rest frequencies of 112000 and 112000 MHz respectively, and delta frequencies of 0 and 1000. The bandwidth is 800 and the integration time is 30 seconds. But say you don't want this configuration exactly - you want a bandwidth of 300 and an integration time of 90 seconds instead. You could modify that configuration easily as follows:

Configure("High redshift CO")
Configure("""
bandwidth=300
tint=90
""")

b) Defining configuration metakeywords directly.

You could also set up the system for Case 20 by specifying your setup metakeywords directly. Notice how this eliminates the need for you to import the gbtsetup function, refer to each metakeyword as g.metakeyword, and eliminates the need to explicitly g.setup() in order for the configuration to take effect.

 
Configure("""
receiver  = "Rcvr40_52"
beam      = "B12"
obstype   = "Spectroscopy"
backend   = "Spectrometer"
nwin      = 2
restfreq  = 112000,112000
deltafreq = 0, 1000
bandwidth = 800  
swmode    = "sp"
swtype    = "bsw"
swper     = 1.0
swfreq    = 0,0 
tint      = 30 
vlow      = 500000
vhigh     = 500000
vframe    = "bary"
vdef      = "Optical"
noisecal  =  "lo"
pol       = "Circular"
nchan     =  "high"
spect.levels = 3
""")

c) Including a previously written configuration script.

If you have already written a complete Python script to perform your configuration which includes import statements and g. statements or simply contains text that that used in the example above, you can refer to that in your observing script or Scheduling Block in this way:

Configure("/path/to/my/directory/my-configuration-script.py")

Step 3: Describe Your Observation.

Your observation is defined by a series of scans and other procedures (such as setting the LO velocity, balancing, etc.), within which you can include Comment statements and Annotation statements. You may use any of the ObservingDirectives that you wish.

Comment statements are printed to the Monitor tab of the Turtle GUI while your observing is underway. For example, Comment("tell me when you get to this step") will print "tell me when you get to this step" in the Turtle GUI Monitor tab when that point in the Scheduling Block is reached. This is a useful feature if you want to print out items to your observing history file in the middle of the process.

Annotation is used to insert a keyword and value into the GO FITS file. For example, Annotation("SESSION", "Second") will insert a keyword SESSION with value "Second" into all GO FITS files that are produced during the current observing session unless this keyword is changed by using Annotation again. To remove an annotation, simply call Annotation with the keyword to be removed, e.g. Annotation("SESSION")

SetSourceVelocity is used to specify the source velocity for the LO1. E.g. SetSourceVelocity(2000.0) Units for velocity are kilometers/second.

Balance is used to balance the IF system. Simply place a Balance() command whereever balancing is required in the script. Balance determines what portions of the IF path need to be balanced based on your configuration. If you wish to override the default behavior, simply pass on of the following arguments to the Balance function: "IFRack", "Spectrometer", "SpectralProcessor", "Rcvr_342", "RcvrPF_1", "RcvrPF_2" (e.g. Balance("IFRack")).

Break is used to pause the observation; this enables the observer to temporarily halt execution in order to perform some activity, such as checking the system after a Balance (e.g. Break()). You may also specify a message to be associated with the Break by passing the message as a string to the Break function, e.g. Break("The IF system should be balanced.  Check it out."). The Break function will timeout and the observation will continue after 5 minutes if no response is given by the observer.

Out of 16 total ScanTypes, all but 1 (OffOnSameHA) are supported in the beta release of the Observing API. Some selected examples taken from the ScanTypes page (more details are available there):

Action	Syntax
Slew to a source from a declared Catalog	Slew("3C48")
Do an OnOff on 3C48, 60 sec per subscan using beam 1	OnOff("3C48", Offset("J2000", "00:01:00", "00:01:00", cosv=True), 60.0, "1")
Nod on 3C48 between beams 1 and 2, 60 sec per subscan	Nod("3C48", "1", "2", 60.0)

There are example observing scripts available for you to review.

User-Defined Scans:

If you have your own custom Scan type, you may use it in your turtle script. If it is contained within a file, simply insert DefineScan("NameOfScan", "/path/to/scan.py") OR

DefineScan("NameOfScan","""
from gbt.turtle.proc.Procedure import Procedure

class myScan(Procedure):
    def __init__(self, arg1, arg2):
        self.arg1 = arg1
        self.arg2 = arg2

    def Execute(self, receiver, scan):
        # do observing stuff here
        pass
""")

Here is an example user-defined scan called QuickPeak. Please refer to ObservingAPIBuildingBlocks for more information about implementing your custom Scan type.

B. Run your observing script.

Step 1: Setting Up Permissions in the Gateway.

Make sure that you and monctrl@wind.gbt.nrao.edu have permission in the Gateway to access both the Antenna and AntennaManager. The on-duty operator can do this for you.

Step 2: Launch Astrid.

To bring up this interface, type: astrid

Step 3: Load your Scheduling Blocks

By default, the "Observation Management" application component will be selected. There are two tabs within "Observation Management": Edit and Run. Select the Run tab.

The Run tab allows you to execute the Scheduling Blocks associated with your project on the telescope. To begin using the Run tab, select your project from the drop-down list. The drop-down list will allows you to type your project name rather than selecting it via the mouse (if you so desire). When typing a project name, the application will try to auto-match what you are typing to an existing project. Once a project is selected, the Job Queue (located beneath the project id) will be populated with every Scheduling Block associated with your project. Also, the session number will automatically be filled in with the next recommended session number. Double-check the session number for correctness before executing Scheduling Blocks on the telescope. You should also make sure that an observer's name (yours) and operator's name have been selected. The observer and operator drop-down lists allow you to type your name and the operator’s name rather than selecting it via the mouse, if desired.

A screenshot of the Run tab can be found here.

Step 4: Execute Your Scheduling Block on the Telescope

To select a Scheduling Block for execution on the telescope, simply click on the Scheduling Block's name within the Job Queue and press the Submit button located beneath the Job Queue. You may also double-click on the Scheduling Block's name in the Job Queue to submit the Scheduling Block for execution on the telescope or right-click and select Submit to submit the Scheduling Block for execution on the telescope. Scheduling Blocks are copied from the Job Queue to the Run Queue when they are submitted for execution on the telescope.

When you submit a Scheduling Block to the Run Queue, it is time tagged with the time when it was submitted. Once accepted for execution on the telescope, the Scheduling Block is moved to the History list where it is time tagged with the time when the Scheduling Block began execution on the telescope. The top-most item in the History list is the most recent or currently executing Scheduling Block. You may modify the execution priority of Scheduling Blocks in the Run Queue via the Move Up and Move Down buttons located beneath the Run Queue. You may also remove Scheduling Blocks from the Run Queue via the Remove button located beneath the Run Queue.

Monitoring Your Scheduling Block

You may monitor the progress of your Scheduling Block as it executes on the telescope via the Observation Management Log. The log is displayed at the bottom of the Observation Management Application Component and is therefore visible from both the Edit and Run tabs. Error messages and other important notifications will appear in red. The log is read-only.

You may save your log to a file on hard disk for personal use via the Export Log button located above and to the right of the observation log at any time during your observation.

There are two advanced user options: Comment and Trace. Comment refers to the time-tagged messages that appear in the log. If Comment is unchecked, no messages will appear in the log. This mode of operation is not recommended for users and is only used for testing/debugging purposes. The Trace field allows the toggling of extra error messaging, which is also used exclusively for testing/debugging purposes.

A screenshot that shows the Observation Management log can be found here.

Managing the Execution of Your Scheduling Block

You may manage the execution of your Scheduling Block on the telescope via the control panel located along the right-hand side of Astrid. The control panel is always visible from any Application Component. The control panel contains state and status information on the Scheduling Block Executor state as well as the M&C system.

The Halt Queue toggle button controls the execution of Scheduling Blocks listed in the Run Queue. When toggled, it turns red and prevents further Scheduling Blocks from being accepted by the Scheduling Block Executor for execution on the telescope. Please note that if a Scheduling Block is currently being executed and the Halt Queue button is pressed, the current Scheduling Block will continue to completion (unless stopped via another mechanism) and then the queue will stop.

The Pause=/=Stop=/=Abort buttons apply to individual Scheduling Blocks. The Pause button acts as an interactive Break command (see the Observing Directives for a description of Break). It pauses the currently executing Scheduling Block. Please note that if a sub-scan is in progress and the Pause button is pressed, the current sub-scan will continue to completion (unless stopped via another mechanism) and then the Scheduling Block will pause. The Stop button stops the current sub-scan (if any) and gives the user a chance to exit the Scheduling Block. The Abort button aborts the current sub-scan (if any) and gives the user a chance to exit the Scheduling Block. The primary difference between a stop and an abort is that with a stop all data that has been taken will be flushed to disk before discontinuing the sub-scan; an abort may result in lost data.

The Interactive toggle button, when not depressed, answers all interactive pop-up dialogs with the "safest" answer, i.e. if a configuration fails, Astrid will automatically abort the Scheduling Block for you. We recommend that you leave the Interactive button depressed and answer all pop-ups interactively.

A screenshot that shows the control panel can be found here.