Use Case: Observatory Mode: Optical Pointing

Last modified: 10apr07

Goals:   Use the optical telescope on an antenna to derive antenna pointing solutions based on observations of stars. This use case is for Interactive observing (manually schedule the SB). It is designed to provide easy access to optical pointing software and results for commissioning with as much interactivity as needed.

This is a relatively simple automatic use case: the correlator is not involved and the data volume is low.

Contact Authors:   D. Shepherd, R. Lucas, J. Mangum

Role(s)/Actor(s):
Primaries:

• Staff Astronomer/Commissioning Team/Operator - Start the ALMA software, generate an optical pointing project with one SB and submit it to the Archive, create an interactive mode array, submit the project for observations in interactive mode, excise bad pointing measurements before fitting, examine final pointing solution, apply pointing solution if errors/results are acceptable.
  

• ObsPrep - Provides a user interface to the Observing Tool (OT) to allow the astronomer to create the scheduling block (SB) that defines optical pointing inputs.
  
• Executive - Starts up the integrated system, provides logging status of the optical pointing procedure.
  
• Scheduling - Allow Operator to create an Array for optical pointing, query the archive for available SBs, and interactively schedule the SB. Update the project status.
  
• Control - Activates the SB, drives the antennas, observes the stars, generates a list of star peak and antenna positions that is integrated into the ASDM and written by Data Capture into the Archive, sends out notification that the procedure is complete. Updates the pointing model when requested by the Operator/astronomer via a python command.
  
• TelCal - Takes the output list of positions, generates a TPOINT-compatible input file, allows astronomer to run TPOINT software to analyze results and generate a pointing solution. Note: TPOINT is considered to be a part of TelCal and all operations by and interaction with TPOINT is controlled by TelCal.
  
• Archive - Repository for the star catalog, SB, ASDM, and TPOINT results.
  
• DataCapture - Provides data flow and notification channel for broadcasts.
  
• Offline - Provides a tool to allow the astronomer to export the optical pointing results from the Archive (asdmExport).
  

Priority:   Critical (optical pointing can be done offline in an ad-hoc way but it is extremely desirable to have this automated for commissioning).

Performance:   Control, Scheduling, & Archive activities must run in near-real time (within seconds), TelCal analysis of the results should be initiated within a few minutes after the data is taken.

Frequency of Use:   There will be ~5 optical pointing systems (OPTs) available for antennas in the ALMA 12m array. All antennas will be able to accommodate OPTs. Optical pointing is expected to be done each time an antenna is put into the array during commissioning or after maintenance at the OSF. All ACA antennas will have OPTs, thus, this mode may be applied to the ACA sub-array periodically (this use case has not been modified for ACA use).

Preconditions:

1. The Optical pointing camera (OPT) is installed on the antenna and the plate scale is calibrated. The calibration results have been placed in a database which will be read by the control software.
2. The Astronomer/Operator has a valid user name and password on console1 (also known as golum at the ATF), they have operator group privileges and access to the shared disk space (/userdata) from their home directory, and they have logged into the operators console (console1 or golum) as themselves.
3. The Astronomer/Operator has started the ALMA software. The following subsystems are active (at least): Control, TelCal, Archive, Scheduling. The Operator interface GUI is available and active. DataCapture is either running or ready for Control to start up when needed (DC runs within the Control component).
   • If the Astronomer/Operator has pre-configured the OMC layout, there is an omc.layout file in their home directory which will define what should be displayed when the OMC is first started and how it should be laid out.
   • The system startup (after typing runOMC) took less than about 3 minutes to start up (assuming the "start ACS" and "Operational" buttons were clicked in a timely fashion).
4. The Astronomer/Operator has checked that the Optical Pointing camera is focused. If it is not, they should manually determine and set the optimal focus. At the ATF, the OPT required re-focusing about once a night because the lens cell is slightly temperature dependent. Further, the OPT should be slightly out of focus to ensure that the star image on the CCD covers several pixels (required to obtain a good fit to the Gaussian peak). Because of the temperature dependence of the OPT focus and the need for human judgment, this step has been made a manual pre-condition to optical pointing.
5. The OT should be able to generate the optical pointing project with one SB.
6. The Scheduler is ready for Astronomer/Operator input to create an interactive array and submit an SB or in Dynamic Mode (to automatically schedule an optical pointing SB that is high priority).
7. The Control subsystem is active and ready to execute an SB when requested by the Scheduler or Astronomer/Operator.
8. TelCal is active and ready to process data.
9. The Archive permissions are set to allow the Scheduler/Project Manager and DataCapture to write to the Archive.
10. A verified, standard mode optical pointing script has been written and is available for insertion into an SB in the OT project. The current standard mode optical pointing script writes the star position centroids to data capture (for later archiving) and to a data file on disk in TPOINT format. The disk file contains additional information, in fields delimited by comment characters, that cannot be put in the ASDM (such as separating the offsets due to the current pointing model and the offsets measured using the camera).
11. The latest/best pointing model has been loaded using the command
    • SetPtModel  - -name=ALMA0x  - -file=ptmodel.mod 
    where ALMA0x = ALMA01, ALMA04 or some other antenna name.
12. All documentation referenced below and additional detailed documentation on specific subsystems is available at: http://almasw.hq.eso.org/almasw/bin/view/Usertests/AcceptanceAIVDocumentation20070411

Basic Course:

1. Astronomer/Operator creates an optical pointing project/SB with the Observing Tool. An input list of stars is generated by the OT in the SB and selected stars are put in a random order. The Astronomer clicks the option for the standard mode script to be used.
2. The Astronomer/Operator requests that the OT verifies the scheduling block for optical pointing and places it in the Archive.
3. The Astronomer/Operator uses the Scheduling GUI interface to select a sub-array with a single antenna to be used for interactive observing. The selected antenna has the optical pointing camera and associated hardware installed.
4. When the interactive array is created the Scheduler queries the Archive for a list of available SBs to run. If desired, the Astronomer/Operator can narrow the query parameters to show fewer SBs if desired (e.g. only those beginning with "OPT"). The optical pointing project/SB is one of them.
5. The Astronomer/Operator selects the optical pointing SB via the Interactive Scheduler GUI interface and clicks on the "Execute" button.
6. Control creates an ExecBlock (EB) and begins execution.
7. ExecBlock execution events (controlled by the standard mode script that is referenced in the OT project - if this script is modified then the specific details below may change):
   • Once a star is selected, determine if the elevation is greater than a specified angle above the horizon.
   • If the star is above the elevation limit, Control commands the antenna to slew to the source. If the star is below the elevation limit, then a message will appear in the log window saying that this star is being skipped and the telescope will move on to the next star (after a specified time defined in the script).
   • If a star is visible, then Control commands the camera to take a CCD frame. Control finds the peak on the frame.
     • Alternate course 1: The star is not visible, too faint or too close to the edge: The star position can not be determined when the brightest pixel in the image is within 9 pixels of the edge (the peak finding algorithm does not work in this case) or when the signal to noise ratio (SNR) is below a user specified value. The SNR is computed using the brightest pixel and the noise in a region of the image that does not contain the brightest pixel. When either of these circumstances occur, then Control sends a message to the log window saying that the star is being skipped because its parameters could not be determined.
     • Alternate course 2: The star is below the horizon: The OT can be used to select only stars above a user-specified elevation limit above the horizon at a given LST time at the ATF or OSF. The Astronomer can either produce a new or modified project/SB each time optical pointing is run (to set the LST & elevation limit) or generate projects appropriate for different ranges of time (so an appropriate SB can be selected from a list of SBs at any given time). But occasionally, a star may be below the elevation limit. If this occurs, then Control sends a message to the log window saying that the star is being skipped because it is below the horizon.
   • Control writes the derived peak and antenna positions to a disk file in TPOINT format. Control also writes additional information for each data point in this file that cannot be put in the ASDM (e.g. such as separating the offsets due to the current pointing model and the offsets measured using the camera).
     • Note: this step is implemented in the standard mode holography script and was introduced at the ATF to support early commissioning and verification activities. If this step is not desired, then the standard mode holography script must be modified but no control software changes are necessary.
   • Control writes the derived peak and antenna positions to DataCapture.
   • DataCapture collects all results in ASDM format until the end of the SB.
   • Control selects the next star and repeats above procedures.
   • When all stars in the list have been observed, then optical pointing is complete.
8. While the ExecBlock is running:
   • Scheduling indicates the SB is running by showing an 'R' in the status column next to the SB name.
   • Control sends log messages to the logging channel in DataCapture and the logs are then relayed to the Archive. Log messages are displayed on the logger interface of the Operator GUI.
9. When the ExecBlock is complete the following things happen:
   • Control sends out an 'End' event and generates a log message saying that Optical pointing is complete.
   • The log message is displayed on a logger interface of the Operator GUI and sent to the Archive.
   • The 'End' event will be used by Scheduling to update the status of the schedule block in the Scheduling GUI.
   • The 'Data Flow' tab or sub-panel on the Operator GUI will indicate that the Exec block is complete (1-0 --> 1-1) and the total number of stars observed will be displayed as the total number of scans taken).
   • Project Manager (Scheduler) detects the completion event on the ExecBlock from the Control subsystem and updates the Project Status in the Archive.
10. The Astronomer/Operator notes the UID identifier in the OMC 'Data Flow' tab (e.g. uid://X00/Xf/X2) and exports the resulting ASDM from the archive by typing the following command from an x-term window:
    • asdmExport uid_number
    Where the uid_number is the UID identifier noted above. The ASDM is written to disk. The name will be similar to the UID identifier except that '/' or ':' characters will be replaced by '_' underscore characters since disk file names are not allows to have these special characters (e.g. uid_ _ _X00_Xf_X2)
11. Processing of the optical pointing data is done offline by the Astronomer/Operator to allow for flexible interaction with the software and data editing. The following steps involve an interface to TelCal and the Archive:
    • In a terminal window on the operator console, the Astronomer/Operator moves to the directory in which the ASDM file was downloaded. They then start python by typing 'python'. At the python prompt (>>>) the Astronomer/Operator converts the ASDM to TPOINT format and reduces the data. Typical commands that do not include editing are:
      • from OpticalPointing import *
      • opt=OpticalPointing('ALMA01') # e.g. for antenna 1.
      • opt.setDefaults()
      • opt.check()
      • opt.setDataSet('uid_file') # where uid_file is the name of the exported ASDM, e.g. uid___X00_X2_Xf.
      • opt.reduce()
      • opt.getResults()
      • opt.getTpointFile()
      • opt.getTpointPlotFile() # ghostview tpoint.ps file created on disk.
      • opt.reduceAndArchive() # to archive the results
      • opt.cleanup()
      • Ctrl-D # to exit python
    • The Astronomer/Operator will be able to flag bad data and re-run TPOINT with the edited data and re-determine solutions until an acceptable solution is found. Once the solution is good, the Astronomer can run the "opt.reduceAndArchive()" command above to archive the pointing solution.
    • Previous pointing solutions that were written to the Archive should be tagged as earlier versions if another, better solution is written to the Archive.
    • To load a pointing model that has been written to disk, the Astronomer/Operator must create a file on disk that can be loaded manually. Copy the results that are printed to the screen when you copy "opt.getResults()" and put the coefficients into a text file on disk.
    • The Astronomer/Operator loads the pointing model using the command from a terminal window on the operator console:
      • SetPtModel - -name ant_name - -file pting_file # where ant_name = antenna name (e.g. ALMA04) and pting_file = the file you created on disk (e.g. aec.29mar07.mod). Note that you need 2 dashes before the name and file options.
      • "SetPtModel -h" gives help on the inputs expected for this command.
    • To query the system to determine if a pointing model is applied, the Astronomer/Operator types in a terminal window on the operator console:
      • GetPtModel - -antenna ant_name # where ant_name = antenna name (e.g. ALMA04) Note that you need 2 dashes before the antenna option.
      • "GetPtModel -h" gives help on the inputs expected for this command.

Postconditions:

1. Pointing data is on disk and in the Archive
2. The system logs are available in the Archive.
3. The pointing model result is in the Archive (Cal DB)

Issues to be Determined or Resolved:  

1. None at this time.

Notes:  

1. Use Case created by D. Shepherd based on many conversations with Robert Lucas, Allen Farris, Jeff Mangum, Alan Bridger, Ralph Marson, Joe McMullin, Brian Glendenning, Joe Schwarz Sohaila Lucero and Jeff Kern. Robert Laing's comments have also been taken into account.