NRAO Home  >  Green Bank  |  Wiki Topic:    GB > Software > BalanceAPI

Changes | Index | Contents | Search | Statistics | Go

GBT Balance API

• GBT Balance API
  • 1. Introduction
  • 2. The Basic Design
    • 2.1 The Balance class
    • 2.2 Optional Parameters
  • 3. Known Issues
  • 4. Core Team

1. Introduction

The astronomical observer has three choices, and should follow the instructions on other pages, linked here:

• Issue commands to balance within your Scheduling Block (turtle script)
• Balance interactively using Astrid, if you need to do so while a scan is in progress
• Balance interactively using the config_tool application, if you are not observing using Scheduling Blocks (turtle scripts)

2. The Basic Design

The Balance API consists of the following classes: Balance, acs, pf, sp and ifrack. The programmer using the API needs only to create a Balance object. All functionality of the underlying classes are exposed through the Balance class interface.

2.1 The Balance class

The Balance class serves as the interface to the API. Its function is to promote a clean interface to the observing API. Its use can most easily be described by an example.

First a Balance object is created with a list of the managers to be balanced.

          b = Balance(["pf", "ifrack"])

If no parameters are specifed (e.g. if b = Balance() is used), the ifrack is the default device.

To perform the balance, the balance method is called.

          b.balance()

The balance method performs a balance on each of the devices specified. In this example, balancing is performed with the default balancing options for each device. The devices are balanced in the order specified in the list. In the above example, the Prime Focus receiver is balanced first, followed by the IFRack.

2.2 Optional Parameters

An optional parameter to the balance method can be provided. This parameter must be a dictionary that contains 1 or more of the following balancing options. Items which are not in the dictionary are assigned their default values. Non applicable options are ignored.

The supported keywords and their default values are:

              target_level =  -11   Applicable when balancing the SpectralProcessor (sp) 
              port = (1..41)        Applicable to the Spectrometer (acs)       : 
              sample_time = 2       Applicable when balancing the Prime Focus Receivers (pf) 
              cal = 'off'           Applicable when balancing the Prime Focus Receivers (pf)                                    

Supported dictionary keys/value type are:

        target_level / float
        sample_time  / int
        cal / string containing "on" or "off" -- other values will be treated as if "on" was specified
        port/ tuple containing integers from 1 to 41

An example of a dictionary containing valid options and its use in a balance method call is:

         opt = { "target_level": 4, 
                 "sample_time" : 5,
                 "cal"         : "on",
                 "port"        : (9,13)
                }
         b.balance(opt)

3. Known Issues

The Balance API is a programmer's interface to balancing. The Observation API (and thus Scheduling Blocks and the turtle application) provide a simplified syntax to balancing. The observer should be aware that when he or she is writing a Scheduling Block, the syntax described in the "Balance" section of ObservingDirectives should be used. If the observer is balancing manually to satisfy special requirements of his or her observing, and does so from the Python command line or the Astrid "Command Console", the slightly more verbose syntax described at BalanceUsage#BalancingWithAstrid must be used.

4. Core Team

-- MelindaMello - 02 Dec 2004