Creating Scripts With the LBC OB GUI

1) Introduction

2) Getting Started with the OB GUI

3) Creating and Saving a Single OB

A) Target Package:

I) Entering the Bookkeeping Information

II) Entering Target Information

III) Interactive Pointing

B) Observation Description:

I) Dithering

II) CCD Parameters

III) Integrations

C) Constrain Sets

4) Creating and Saving a Set of OBs

Introduction

Observing with the one or both Large Binocular Cameras at the Large Binocular Telescope requires scripts that configure and control the instrument and telescopes. All scripts or Observing Blocks (OBs) for LBC are in xml format and can be produced using the Observing Block Creation GUI provided by the LBC team. Below are detailed instructions for how to use the GUI to create LBC compatible OBs.

We highly recommend that an observer new to LBC review the Scripting Basics page FIRST to get a general description of the strategies necessary to use LBC before proceeding with the following instructions on the how to produce scripts with the OB GUI.

 

Back to top


Getting Started with the OB GUI

The following is a step-by-step guide to using the OB GUI. More information can be found in the document, GUI_MANUAL by Stefano Gallozzi. The OB GUI may be downloaded by clicking on the “Binaries” link here. It has been written for and tested on Windows and LINUX platforms, but does run also on the Mac OS.

To launch the OB GUI, go into the directory created by unzipping the file (where the GUI.jar file is) and type java –jar GUI.jar. On windows machines, double click on the GUI.jar icon.

A window should pop up with the title, Main Window. There is a set of buttons along the top which are divided by functionality into three main groups: (1) the three left-most buttons (yellow) create, delete and open Folders; (2) the five red buttons to the right of these deal with Observing Plans and are currently not used; and (3) the six green buttons after these create, open, delete, export, copy and save OBs. These are heavily used. Note that all of the buttons have text descriptions which will appear when the mouse cursor is brought to rest for about 1-2 seconds on the button. The buttons serve as shortcuts for the tasks listed in the menus (Folders, Plans, OBs) along the row above.

Back to top


 

Creating and Saving a Single OB

 

The first step in creating an OB is to open the folder (directory) where the OB will be saved. If this output folder (directory) does not exist, you can create it — either in an xterm with the ‘mkdir’ command or by clicking the “New Folder” button on the OB GUI and entering the Folder name and the path to it. Open this folder by clicking the “Open Folder” button, which will pop up a browse window in which you can select the folder. The name of the open folder should appear in the top panel of the OBGUI Main Window, just to the left of the red and white “power” button. The left sidebar may or may not show this folder and the parent directory (called “root”), depending on how the folder was created. Do not be concerned if the folder name does not show up correctly here.

When you are ready to save the OB, click the “save OB” button or select “Save” from the “OBs” menu. This will write out a *.ob file in the open folder.

Target Package:

Entering the Bookkeeping Information

When the Main Window is open on the “Target Package” tab, you should see 6 lines at the top, underneath the heading, Observing Block Description. The filename of the Observing Block (OB) to be created will be taken from the Observing Block Name which should be entered here. It is advisable to avoid white space and periods (“.”) since filenames with these characters are either difficult to manipulate in Linux, the operating system on the observer workstations, or not able to be opened by the OB GUI. It is also recommended to keep the OB name shorter than 18 characters, since only the first 18 characters of the name entered here will be written to the header as the value of the LBCOBNAM keyword.

  • Target Name: The name of the object, which can have spaces, number and symbols. The target name specified here is written as the value of the header keyword OBJECT.

  • Class Type: The value of the header keyword IMAGETYP: object, zero, flat, dark, focus, …

  • Proposal ID: Enter the ID number given to your proposal. If you do not know it, enter the PI Name. This value will be written to the PROPID keyword in the primary FITS header.

  • PI Name: Enter the name of the primary investigator. This value will be written to the LBCUSER keyword in the primary FITS header.

  • Observer: Set Observer to your partner name: inaf, az, lbtb or osurc. Either upper or lower case may be used. This value will be written to the OBSERVER keyword in the primary FITS header. In OBs to obtain calibration data (standard stars, biases, flats, darks), OBSERVER should be set to calibration. The lbtarchive from which you retrieve data requires a partner-specific login which allows you access only to data obtained by your partner group. Therefore, it is essential that the OBSERVER value is correctly entered in the OB.

Entering Target Information

Target and Offset and PA information should be entered in the Target Coordinates & Offset and Rotation section of the Target Package window in the OB GUI.

 

Target Coordinates:

RA: The RA may be entered either in the top box as decimal degrees or in the lower set of four boxes as hours, minutes, seconds, and fraction of seconds. You can tab from one field to the next, and as you do, the RA in decimal degrees will be updated in the box above. Make sure that the final value of RA in decimal degrees is correctly corresponds to the hours, minutes and decimal seconds which were entered, because it this value (decimal degrees) that is written to the output OB file and, consequently, read into the LBC User Interface and passed on from it to the telescope control system.

DEC: Similarly, DEC may also be entered either as decimal degrees or as degrees, minutes, seconds, and decimal seconds.

Special Note:
DEC = -90: To signal that the OB should be carried out where the telescope is currently pointing, set DEC = -90. Note that an OB set up like this (without a preset) will not be able to command dithers. When DEC = -90, RA may be anything from 0-360 deg (0-24h).

Equinox of Coordinates: Note that while there is an option to enter either 2000 or 1950 (J2000 or B1950) coordinates, the telescope control does not as yet accept B1950 coordinates. Enter only J2000 coordinates.

Rotator Tracking and Preset LBT: Insure these boxes are checked (or not checked) as you wish. For normal observations, both should be checked.

  • Rotator Tracking: If checked, this enables the rotator to move during the observation to compensate for field rotation and maintain the position angle. During normal observations, this should be checked.
  • Preset LBT: If checked, this enables the instrument to send commands to the telescope control system: among other things to slew to the target, track at the sidereal rate, dither and adjust the position of the primary mirror. For normal observations, this should be checked.

Offset and Rotation:

Position Angle: Enter the desired position angles, in degrees, for LBC-Blue and LBC-Red in the boxes to the right of BArm and RArm in the lower right part of the page. A position angle, PA = 0 degrees, corresponds to the North vector pointing up along the positive y axis, from the center of rotation on chip 2, and the East vector pointing to the left, along the negative x axis. The position angle is defined as the angle of the positive y axis from the North vector, measured from North through East.

Offset: Offsets to the target coordinates can be entered as RA and DEC offsets (in arcseconds). These offsets will not be directly written to the OB file that is generated by this GUI; only the decimal degree RA and DEC values in the “Target Coordinates” section are written to the output OB. Therefore, to implement an offset from the base position, you MUST click on the button just above the box for the DEC offset in order to add these offsets to the RA and DEC target coordinates.

Proper Motion: Proper motions in arcsec/yr may be entered. These are converted to radians per century, the units required by the telescope control system, before being written to the output OB. However, at this time (October 2010) LBC proper motions are not yet handled in the telescope control system; whatever is entered in these boxes is currently ignored.

Interactive Pointing

Click on Interactive Pointing to see a visualization of your target. This will appear as an outline of the detector array over an image from the Guide Star Catalog. The outline is displayed by default for all dither positions together, and the pull down menu under “Ditherings” allows you to select individual dither positions or chips. Click the magnifying glass to zoom, unzoom or return to the original size. In the bottom portion of the page, the position angle and coordinate offsets can be adjusted. Click Recenter position to update the target coordinates and position angles in the Target Package page. The option to “Download Image and Open Jsky” is not working at this time.

Observation Description:

Click the Observation Description tab to display this page. In the top section, the dithering offsets are determined, and in the bottom section, the CCD Parameters and the integrations are set up.

Note that one arm is designated as Master and the other Slave. Since 26-March-2011, the binocular version of the LBC software has been used. The Master/Slave terminology has become obsolete, and the Master/Slave designation in the OBs is no longer relevant and can be safely ignored.

There are 8 rows per channel; each row can use a different filter or different integration time. When multiple filters (or multiple rows) are used:

  • Observations will always be executed with the outer loop over dither postion and inner loop over filter(over row), i.e. at the first dither position, all of the requested filters will be cycled through before the telescope is commanded to move to the next dither position.

  • Try to make the total times to cycle through all of the filters in the Blue and Red channels of equal duration, so that one channel is not left idle while the other is completing an observation.

  • Do not leave the first row blank or gaps between the rows.

Specifying the Dither Pattern:

There are various parameters that can be set to determine the list of RA and DEC dithering offsets. The most important buttons are described below. Three important notes:

  • All Dithering Offsets are absolute, not relative.

  • Although there are 9 areas where values may be input to specify or modify the dithering pattern, these “boil down” to 3 items which are written to the GUI and read by the LBC User Interface: the Number of Dithering Offsets, and the sets of RA and DEC Dithers. After you have set up the dithering sequence, please check that the values in these boxes are what you want.

Dithering Pattern: Select a Dithering Pattern from the drop-down menu near the top middle of the window. Many patterns are available. These are described later and depicted in the plots that are linked to this page.

Dith Angle: This will automatically be filled in with the LBC-Red Position Angle which was indicated in the target page. For the patterns that were developed to fill gaps or move a star from chip to chip (the 4-point, 5-point, 9-point or 10-point patterns), the intention is to offset in detector coordinates. To calculate RA and DEC offsets which will do this (move stars strictly along rows and columns) the position angle is needed. Should you wish to edit this value, click on the box after having selected a Dither Pattern which is not one of the 4-point, 5-point, 9-point or 10-point patterns. You may then reselect one of these patterns and click “Calculate” to determine the set of offsets with this new angle. User Provided patterns are already input in terms of offsets, so Dithering Angle and Scale are not relevant.

Dithering Scale: Used by the 5-point, 9-point, 10-point, Circular, Rectangular and Random Dithering Patterns to set the scale of the dither offset. Keep in mind that the gaps between chips are about 18 arcseconds wide. User Provided patterns are already input in terms of offsets, so Dithering Angle and Scale are not relevant.

Calculate: Once the Dithering Pattern is selected and the Dither Angle and Dithering Scale are set, click the “Calculate” button to calculate the set of RA and DEC dithering offsets. The boxes to the right of RA Dither and DEC Dither should be populated with a set of comma-separated numbers, one for each dither position.

Other Dithering Options… There are options available to select the “Starting Item”, and to offset the entire pattern (“Offset X axis” and “Offset Y axis”), however these are seldom used.

The Dithering Patterns are described in detail below:

  • Random:

  • 4-point default: designed to position the target on the center of each of the four chips. This is the pattern used in the Calibration OBs for observations of standard stars.

  • 5-point default: in a left (5-split-L) or right (5-split-R) leaning 5-dice pattern to fill gaps;

  • 9-point default: in a left (9-split-L) or right (9-split-R) leaning 3×3 grid to fill gaps. These have been separated into 3 sets of 3-point dithers.

  • 10-point default: a left (10pt-L) or right (10pt-R) leaning 10-point grid to fill gaps.

  • Circular

  • Rectangular

  • None

  • User Provided: When this option is selected and the “Calculate” button is clicked, a browse box is opened in which you can select the ascii file which contains the custom RA and DEC offsets, in arcseconds. The format is as follows, with one offset per line and with the RA and DEC offsets separated by a semicolon:

  0.00; 0.00
-18.00;-36.00
 18.00; 36.00
-36.00; 18.00
 36.00;-18.00

 

Editting the CCD parameters

Click “Edit CCD”. This brings up a window entitled “Chip Settings”.

  • Detectors: A check-mark in the box to the left of the chip number indicates that it will be read out. The available options are all four chips or chip 2 only.

  • Readout mode: Read-out mode should always be slow.

  • Binning: 1×1 binning should always be selected. 2×2 binning is not yet offered. With the Red Channel, 2×2 binning may work, although chip-to-chip differences in the bias levels do not correspond with those for the unbinned biases and this is not yet well understood.

  • Shutter: Check the box if you want the shutter to open. Shutter use is indicated by the picture on this window and on the Observation Description page.

  • Window Parameters: Windowing is only possible in rows, and the same settings are used for all detectors that are selected. Enter the range of rows to read out in the boxes for Minimal Y and Maximal Y. Note that Minimal X and Maximal X are always 1 and 2048. The subregion indicated applies to all chips in use.

To close the window and store your selections, click Modify Settings, not Exit! Exit will exit the window but will not modify the settings.

Setting up the integrations

Back in the Main Window/Observation Description, set up the exposure times for each filter to be used. To enter data in the table, double-click anywhere along the header row to allow input of exposure times. Select a filter from the pulldown menu under the “filter” column. Usually you will enter the number of exposures per dither position (NExpo) and the single exposure time (SingleTExpo) in seconds. The total exposure time (TotalTExpo) is calculated as:

TotalTExpo(s) = SingleTExpo(s) x NExpo x NDitherPositions

After making changes to one of the columns, double-click on the headings of the other columns to update their values. Note that the values that are stored to the output OB file and consequently read by the LBC User Interface are: the number of exposures (Nexpo), the single exposure time (SingleTExpo) and the Filter. The total exposure time is only displayed as an aid in planning the observations. It is also not re-calculated by the program itself when dither, number of exposure  or single exposure time changes.

ETC: Click on the GIF in the left-most column to bring up the Exposure Time Calculator (ETC). You can use this to determine exposure times needed to reach a given signal-to-noise ratio and then fill in the table from the ETC. The ETC is also available from the LBC homepage in Rome.

Focus (engineering use only): From the Observation Description window, it is also possible to set up OBs which step through focus. This functionality is available only for OBs of Class Type FOCUS (specified in the Target Package) and is used primarily for engineering. Click on the “bull’s-eye” to the right of the “Edit CCD” button and a new window will open in which you can enter the starting focus position and the offset in mm. One focus step per exposure is assumed, and the number of exposures is what was specified by NExpo. Click Modify Settings to save the information and close the window.

Constrain Sets:

This allows you to enter condition constraints for the observation, e.g. elevation~60-70 deg, photometric, high priority, seeing < 1arcsec. Be aware that these constraints are not used by the LBC Control software and observers often do not read them either; constraints should be indicated in the observing proposal or README file.

Back to top


Creating a set of OBs

To create a set of OBs which use the same configuration but differ only in pointing and position angle:

  1. Set the instrument configuration in the “Observation Description” tab, and

  2. Select New OB using either the New OB icon on the top icon bar or through the OBs menu.

  3. Click the OB List button. This opens a new window which allows you to enter the data manually or to select a file, which contains one line per target (up to 100 targets) in the following format: ob name; target name; class type; RA [dec degrees]; DEC [dec degrees]; epoch; B-Arm position angle; R-Arm position angle; Proper Motion RA; Proper Motion DEC.

  4. After the list or target data are entered, click “OK Save Them” and all of the OBs will be created and saved. Below are some lines from a sample file:

    wt000001;000001;object;358.203767;-85.895506;2000.000000;0.000000;0.000000;0.000300;0.016000 
    wt000002;000002;object;293.179646;-81.530525;2000.000000;0.000000;0.000000;0.023600;-0.053000 
    wt000003;000003;object;185.340638;-80.061558;2000.000000;0.000000;0.000000;-0.021300;-0.008000 
    wt000004;000004;object;59.302004;-76.510811;2000.000000;0.000000;0.000000;0.004300;0.039000 
    wt000005;000005;object;288.589596;-77.047883;2000.000000;0.000000;0.000000;-0.000400;0.017000 
    wt000006;000006;object;153.119279;-76.077500;2000.000000;0.000000;0.000000;0.004500;-0.013000 
    wt000007;000007;object;13.282362;-74.651553;2000.000000;0.000000;0.000000;0.061300;0.023000 
    wt000008;000008;object;233.313454;-73.543803;2000.000000;0.000000;0.000000;-0.002400;-0.010000 
    wt000009;000009;object;88.769146;-72.814744;2000.000000;0.000000;0.000000;-0.009300;-0.061000 
    wt000010;000010;object;302.644600;-71.642242;2000.000000;0.000000;0.000000;-0.007300;0.026000 
    wt000011;000011;object;153.368129;-71.668844;2000.000000;0.000000;0.000000;-0.018600;0.024000
    

Back to top