Focal Station Commissioning Tools

Binocular Operation

Preset Both Sides

Sync Preset

The following steps will preset the telescope in fully binocular mode with the possibility of different types of preset (eg TRACK or ACTIVE or ACE, etc) with different instrument and focal stations on the two sides (eg LCBG and RFBG).

Before he telescope operator must Authorize the appropriate Instrument/Focal Station combinations on both sides of the telescope via the IIF GUI.

The steps are:
  1. An IDL process with the appropriate setup must be started so Doug's binocular operation routines are available. If you are operating from the LBTO (or AOeng) accounts, this is the default setup. From other accounts the file /home/lbto/binoc_setup should be sourced in the terminal where IDL is started
  2. Register the IDL process with the IIF
  3. Set the parameters for the presets on LEFT and RIGHT
  4. Send the binocular preset request to IIF. Many commands are sent to the IIF, but the ones that make the presets Synchronous are the Binocular Control SYNCPRESET sent to both sides. A PresetTelescope must then be sent to both sides before the telescope moves and the presets are process on both sides.
  5. If preset is Active, then Wait for the Active Optics to reduce the wavefront error to < 1000 nm rms (see GCS GUIs)
  6. Request AO Loop to close.

The command for a binocular preset are:
  1. % source /home/lbto/binoc_setup (likely the default now)
  2. % idl
  3. IDL> iif_register, /TCS
  4. (Set the preset parameters for both sides)
    • IDL> iif_preset, BS9177, MODE=ACE, GS=10, RS=0, PA=-90, /RIGHT
    • IDL> iif_preset, BS9177, MODE=ACE, GS=20, RS=0, PA=90, /LEFT
    • IDL> iif_binoc_preset
  5. Wait for Active Optics collimation to < 1000 nm rms (see GCS GUIs) ON BOTH SIDES
  6. Close AO Loop
    • IDL> iif_binoc_runao

Preset One Side

If a preset on one side fails for some reason during a binocular preset, or the preset is cancelled during operation (e.g. lost guide star, AO loop open, etc) it is possible re-send a preset to only one side. The other side will remain in its current state.

The steps are:
  1. IDL> iif_preset, /RIGHT
  2. Wait for Active Optics collimation to < 1000 nm rms (see GCS GUI)
  3. IDL> iif_runao, /RIGHT

Collimation Model

Collimation Data Collection

The data collection for a new collimation model is performed by hand. The telescope is collimated and then range balanced at several (say 8) elevations and then an on-axis image is acquire (only the header information is needed, not the image itself).

The step to collect the data are:

  • loop over 8 stars at 8 elevations
    1. collimate on the on-axis star
    2. run iraf routine rangebal
    3. take IRTC image (need only header M1, M2 info)
  • loop done

Collimation Data Analysis

Send Andrew a list of the IRTC images collected at the range of elevation. Andrew pulls the needed information out of the headers and runs the IDL routine (I think) to build a collimation model.

Need to include a list of Andrew's steps here

Once a new collimation model has been determined (actually it is a matrix of coefficients) and a file created it must be copied into a directory where PSF can find it. On any of the tcs or obs machines on the mountain, the directory is:

The file names indicate the side, mirror and focal station. A partial listing of this directory shows:

Where DX/SX is the side, PM/SM/TM is the primary, secondary or tertiary mirror and F/C/B/D is the front, center, back or direct focal station. Be sure to make a copy of the current collimation file (to something like DXPMIRTCFCollimation.20101222.dat) before copying in the new file.

Pointing Model

Pointing Model Data Collection

The IDL routine ptmodel_collect (click to view description) automatically collects pointing model data by sending a preset request to a pointing star and collects an image from either the science instrument at the current registered focal station or with the guide camera. These images are used to determine the offset of the pointing star from the hotspot where the star should have landed. This offset information is used, along with log information from the PCS, to determine a new pointing model. This IDL routine writes a file named "ptmodel.log" with a list of pointing stars used and the name of the image collected. This file can be copied in to the TWiki and soon can also be read by ptmodel_process_set to calculate the new pointing model from these data.

ptmodel_collect has two main modes, taking images with a science instrument (currently MODS or IRTC) or with the guide camera.

Science Instrument Collection
% cd data
% mkdir -p 20131215/rfbg
% cd 20131215/rfbg
% idl
IDL> iif_register, RFBG
IDL> ptmodel_collect

The steps taken if a science camera is available are:
  • Copy the required files to the current directory
  • Loop until Ctrl-C is pressed
    • Call Marco's "Pointingstars5" routine to find the next star (Best now to use and take at least one full pass of 20-degree stars ... ~25-30stars)
    • Find an appropriate guide star for this pointing star
    • Preset the telescope in ACTIVE mode to this pointing star, with the guide star on the Y-axis
    • Collimate the telescope to the given wavefront error
    • Preset the telescope in TRACK mode to this pointing star with PA=0
    • Collect a set of images with the science instrument
    • Write the pointing star name and image name to the logfile
  • End loop

Guide Camera Collection
% cd data
% mkdir -p 20131215/rfbg
% cd 20131215/rfbg
% idl
IDL> iif_register, RFBG
IDL> ptmodel_collect

The steps taken if a science camera is available are:
  • Copy the required files to the current directory
  • Loop until Ctrl-C is pressed
    • Call Marco's "Pointingstars5" routine to find the next star
    • Find an appropriate guide star for this pointing star
    • Preset the telescope in ACTIVE mode to this pointing star, with the guide star on the Y-axis
    • Collimate the telescope to the given wavefront error
    • Preset the telescope in ACTIVE mode to this pointing star, GS=0 and PA=0
    • Write the pointing star name and the GCS acquisition image name to the logfile
  • End loop

If this script fails for some reason (eg a preset fails), the script can be restarted part way through the list with the command:
IDL> ptmodel_collect, START=5

where 5 is the fifth grid in Marco's Pointingstars5 routine.

Pointing Data Analysis (in progress)
  • Measure pointing star centroids if the data were not collected in GUIDE or ACTIVE mode.
  • Generate new pointing model (D.Thompson)

  • Copy new model to ~telescope/TCS/Configuration/PCS/
  • Update LUCIFER entry for LEFTPOINTINGMODEL in PCSInstrument.conf
  • Re-authorize LUCIFER on IIF GUI to read in new pointing model
  • Test new pointing model by pointing to a few stars or taking an additional set of pointing data.

Pointing Model Tips from Dave

Make sure to start the pointing log on PCS when taking pointing model data!

It is OK to correct the pointing with IE and CA during the run as the pointing log uses the mount AZEL directly. If you need to tweak the collimation, it is probably OK to do it all with M1, but I typically only need to manually tweak the focus a little if things are stable.

A "minimum" dataset consists of the first 12 cells, from which I can make a decent pointing model (<6 arcsec rms I would guess). The next 16 fill in between the first 12, then the next 24 fill in more between the first 28, and the final 36 complete the pattern. The full cell list has 88 positions, so if you take pointing data, take sets of 12, 28, 52, or 88 points. If you are diligent, you can take ~25 data points per hour with LUCIFER.

More details on Marco's pointing star program

Marco has set up a script for selecting optimally distributed pointing stars. It lives in /home/LBTO/POINTING

You run it by copying it to a local scratch directory and saying: ./Pointingstars5

The program waits for you to input the "cell" number, just start with 1 and increment each step.
For example, I just ran it and it returns:

66 WT10_355 03 45 27.557 +47 39 37.25 0.00210 -.02700

The "1" is what you type (cell number), the next line is the star info (cell number, ID, RADEC, pmRADEC). The program has the full WT10 and ACT catalogs in it, it will give you the star closest to the middle of the requested cell. You then do a "pointto WT10_355" and get the star on the detector (acquisition camera is OK) with a spiral search if necessary. Once there, take a short exposure and note the image number so I can pull the UT out of the image header to match to the pointing log file. It would be good to take all of the data with the acquisition camera at a PA of close to zero (makes my job easier later), so LUCIFER will need to be at 180.3. If you can use LUCIFER, then PA=0 of course.

If there is no star, the program returns cell number 999 and the coordinates for the center of the cell. Just skip it and try again later. The starting position of the Pointing Model Acquisition is at NE, so ask the OSA to put the AZ at ~ +400 degrees. The cells are distributed such that if you will not have to unwrap the AZ during the scan of the entire AZ range, although it is not a problem for the pointing model if you unwrap in the middle.

-- JohnHill - 15 Jun 2008 -- DougMiller - 26 Oct 2009

Guide Probe Transformation

Transformation Data Collection

These instructions for transform_collect have been updated for binocular operation - 10-Sep-2017 - JMH and 31-Jan-2020 - DLM.

This is the procedure for collection of AGw Transformation Data with LUCI or MODS images of the on-axis star, at various guide star locations in the field. The routine tranform_collect switch automatically between focal stations according telescope authorization and thus between LUCI and MODS image collection.

The initial transform needs about 25 stars. Seeing should be no worse than 1.0 arcsec. A better transform needs 50 stars in 0.8 arcsec seeing. After a new transformation is measured and installed, a confirmation data set requires only 12-15 stars with a maximum seeing of 1.5".

The IDL routine reads a file containing the target star and a list of off-axis guide stars, presets to the target star with each of the off-axis guide stars, collimates and acquires an on-axis image for each of these presets. A repository of target and guide star files lives in /home/LBTO/idl/wfsc/transform/lists . Select one of the Stone fields close to the meridian listed in StarCharts. Only these Stone fields with good astrometry and proper motions are useful. This IDL routine writes a file named transform_"instrument".log with a list of guide stars, wfsc image and on-axis images. This file, after some editing, can be read by transform_process_set (click to view description below) which calculates the transform from these data. These instructions assume that LUCI has been configured with N3.75 camera and the pointing mask (a.k.a. N30 field stop), and that the scripts which command LUCI to take an image are working. Update the IMCS status on MODS red channel if you are using MODS.

The *.list file should look like:

41   -90
45   -90
106  -90
55   -90
68   -90
24   -90

where the field is Stone_E (name of catalog), the second line lists the guide star to position on-axis, and the remaining lines contain guide star information: the first column is the guide star and the second is the Position Angle. Note: a single position angle for all guide stars is best, but a range of position angles of less than 30 degrees.

The list of possible flags to the routine Transform_Collect can be displayed on the IDL terminal with the command:
IDL> transform_collect, /help

Monocular Transform

For monocular operation, do the following as user lbto:

  • send an ACQUIRE preset to tune up the pointing on or near your target field
% cd /home/lbto/data
% mkdir -p 20131215/rfbg
% cd 20131215/rfbg
% idl
IDL> iif_register, RFBG
IDL> transform_collect

A dialog box will popup and you can choose the target star list to use. Once you make a selection, the script will proceed.

It may ask you if you want to continue to collimate if
it does not collimate below 400 nm rms in the given
number of iterations.  Yes iterates more, No continues
in the script to collect the next guide star data set.

If this script fails for some reason (eg a preset fails), the script can be restarted part way through the list with the command:
IDL> transform_collect, EXP=4.0, START=5

where 5 is the position in the list of guide stars in ~/idl/wfsc/transform/lists/*.list where you want to start.

Binocular Transfom

For binocular operation, do the following:

You wil need a syncronized binocular preset to the field before starting. This can be done with IDL (see above), or by the telescope operator.
% cd /home/lbto/data
% mkdir -p 20131215/rfbg
% cd 20131215/rfbg
% idl
IDL> iif_register, RFBG
IDL> transform_collect

Then in a second xterm window, start it for the other side. Because all presets are to the same target star, all of them can be asynchronous and the two scripts run independently.
% cd /home/lbto/data
% mkdir -p 20131215/lfbg
% cd 20131215/lfbg
% idl
IDL> iif_register, LFBG
IDL> transform_collect

(end of the September 2017 updates)

Transformation Data Analysis

The .log file written by transform_collect will have lines of information that are not needed. Thus, before the transformation data can be analyzed the log file must be edited.
% cd /home/lbto/data/20200108/lfbg
% cp transform_lfbg.log lfbg.log
% emacs lfbg.log   (or you favorite editor)
     => make corrections and save

The form of the .log file should like like:
#Title LUCI1 Transformation 20200109
#Date 20200109
#Type agw_transformation
#Station LFBG
#Instrument LUCI1
#Center 1012.0 1064.0
#Data_Dir /Repository/20200109
#Bg_Available 1
#Dark_Available 0
#Labels GS          PCS_X         PCS_Y      AGW_X_req     AGW_Y_req      AGW_X_ach    AGW_Y_ach       RotAng        PosAng     Image Num          Image File          Image Type
         3         -0.070        -0.222         0.062       612.427         0.088       612.400       205.348      -135.000        10       luci1.20200109.0010.fits   Background
         3         -0.070        -0.222         0.062       612.427         0.088       612.400       205.348      -135.000        09       luci1.20200109.0009.fits   On-Axis        
        70       -161.751        30.526       161.946       580.747       161.985       580.734       204.603      -135.000        11       luci1.20200109.0011.fits   Field        
         9        -79.733        11.686        79.845       600.066        79.858       600.063       204.316      -135.000        12       luci1.20200109.0012.fits   Field        

For more details about editing log files, click here

The IDL routine transform_process_set (click to view description) reads in the file written by the IDL routine transform_collect (see above), processes the on-axis images and calculate a new AGw Transform. Several output data files and plots.
% cd /home/lbto/data/20200108/lfbg  (of the current directory if the lfbg.log file was just edited)
% idl
IDL> transform_process_set, 'lfbg.log', /pt, /display, /fwhm, /show_center

The output on the IDL terminal of the Transform_Process_Set routine looks like this.

The list of possible flags to the routine Transform_Process_Set can be displayed on the IDL terminal with the command:
IDL> transform_process_set, /help

When the routine Transform_Process_Set is executed there are several data files written in the subdirectory results/. These files have information that are used to create plots plus can be viewed to investigate possible issues or problems. In addition, two interactive plots GUI's are created and displayed. These interactive 3D plots show the X/Y transformation positions relative to the measured positions needed to put the source on the center of the focal plane image relative to the position in the focal plane (PCS X and Y). The purpose of these plots is that it gives a 3D view of the errors that, by left clicking and holding on the plot and moving the mouse, can be shifted and rotated to see if there appears to some trend or problems occured in the transform analysis. Much of this same information is displayed in the other plots created (see below).

In addition, if the LUCI pointing mask is used to correct the source postion due to internal LUCI flexure, two plots will be displayed showing the fitting of the pointing mask point circle (See Plots). If there are problems with analysis, the previous link contains some suggestions. for example the point circle not found, The flag to the transform_process_set, PEAK=[min,max], can be used to change the range of sources (point circle sources) inclueded in the analysis. The sources used are chosen in an anulus where the point circle should be located. A circle is fit to the anulus of sources, the source with the largest fit error is removed and the circle fit performed again. This fit/remove process is iterated until all fit errors are lower than some limit.

Note, if there is a problem with the point mask fitting, The pointing mask image can be viewed via the command
% ds9 ../reduced/luci1.20200108.0019_reduced.fits &

The new transformation to be installed in the AGw Control Software is written in a cut-n-paste form to the file "results/lfbg.conf". The file should be emailed to John H. so the new transformation can be installed. The file "lfbg.conf" looks like this.

To create plots which display several metrics indicating the "goodness" of the new transformation execute:
% cd /home/lbto/data/20200108/lfbg/plot   (or just % cd plot)
% ./lfbg.csh

This script will create three .pdf files saved in the plots directory and these plots will automatically displayed. To understand what these plots mean and how to determine the "goodness" of transformation fits click here.

Offset Accuracy (Dice5)

Dice5 Data Collection

The IDL routine dice5_collect (click to view description) performs the requested number of dice5 pattern offsets and writes a file set1_"dist"_dice5.log with a list of ra/dec or detxy offsets and the corresponding on-axis images. This file can be copied in to the TWiki and can also be read by dice5_process_set to calculate the offset accuracy from these data.
% cd /OldRepository/AGW_Data
% mkdir -p 20101222/dice5/set1
% cd 20101222/dice5/set1
% idl
IDL> agw_set_station, RFBG
IDL> iif_register
IDL> dice5_collect, DIST=5.0, ITER=5

Dice5 Data Analysis

The IDL routine dice5_process_set (click to view description) reads in the file written by the IDL routine dice5_collect (see above) and processes the on-axis images.
% cd /OldRepository/AGW_data/20101222/dice5/set1
% idl
IDL> agw_set_station, RFBG
IDL> dice5_process_set, image, filename, retval

A dialog box will popup and you can choose the *_dice5.log file to read. This routine will output statistics describing the offset accuracy of this set of dice 5 data.

Field Aberration Measurements

Field Aberration Data Collection

The IDL routine field_collect (click to view description) collects a set of field data needed to determine the aberration induced in the wavefront due to the mis-alignment of the primary and secondary optical axes. A file named "filename"_field.log is written with a list of each guide star and names of the wfsc images collected on- and off-axis. This file can be copied in to the TWiki and can also be read by field_process_set (click to view description) , which calculates a quick and dirty estimate of the primary/secondary misalignment and write a data file that can be read by Andrew's Mathmatica routine, which calculates a robust misalignment value. This routine is also used for checking the off-axis field aberration correction for active optics. A repository of target and guide star files lives in /home/LBTO/idl/wfsc/field/lists/ .

  • send an ACQUIRE preset to tune up the pointing on or near your target field

  • send an ACTIVE preset on-axis to get things in approximate collimation while you set things up. Seeing must be better than 1 arcsec to collect useful field aberration data.
  • send a GUIDE preset on-axis so that IDL can take wfsc images (field_collect has problems if GCS takes the wfsc images).
% ssh -X LBTO@obs*
% cd data
% mkdir -p 20101222/sx_field
% cd 20101222/sx_field
% idl_agw
IDL> iif_register, LFBG (or RFBG, LDG, RDG, LPOL, RPOL, etc.)
IDL> field_collect, /IDL

A dialog box will popup and you can choose the target star list to use. These lists are not instrument/agw specific, so they work for any focal station.

If this script fails for some reason (eg a preset fails), the script can be restarted part way through the list with the command:
IDL> field_collect, START=5, LIMIT=300, /IDL

where 5 is the position in the list of guide stars in /home/lbto/idl/wfsc/field/lists/.list* where you want to start, and 300 is the collimation threshold for good collimation.

The field_collect routines writes a log file in the current directory that is in TWiki format, which can be copied and pasted into the TWiki. This file is also used for data analysis, but requires a bit of modification.

You can stop this IDL script anytime by typing
on the terminal where IDL is running. (Yes, Ctrl-c twice.)

Field data can be collected simultaneously on the other side of the telescope in a parallel IDL session.

Field Aberration Data Analysis

Step 0) Check the .log file

The IDL routine field_process_set (click to view description) reads in the file written by the IDL routine field_collect (see above) and processes the wfsc images. The format of the log file needed by the field data analysis routine, field_make_files is:
# Field Data collected on 20110130 for Andrew, High Elevation
#|  GStar  |  wfsc #  |
|  0    |  181           |
|  19  |  182-184  |
|  0    |  185           |
|  18  |  186-188  |
|  0    |  189           |
|  17  |  190-192  |
|  0    |  193           |

  • The first lines in the file with a # sign in the first column are comments and ignored by field_process_set.
  • The first non-comment line is the date
  • The second will be used as the root file name of any files written by the routine (eg bs9126.files).
  • The third non-comment line is the directory path to the images (i.e. /Repository/20190906/GCS/ if GCS took images).
  • The fourth non-comment lines is GCS or IDL depending on which type of data was collected.

The next lines are required to have two columns. The first is the guide star number and the second is the range of wfsc image numbers (eg left_wfscimage000181.fits). Make sure there are no blank lines at the end of the file, but there should be a carriage return after the last line containing information. You should edit the .log file to remove known bad wfsc images, stray headers from a restart, etc.

There are two steps to analyze field data; first the *_field.log file must read the files needed by field_process_set written and then field_process_set is executed.

Step 1) field_make_files

% cd /OldRepository/AGW_data/20101222/field
% idl_agw
IDL> iif_register, LFBG
IDL> field_make_files

A dialog box will popup and you can choose the *_field.log file to read and many *.files files will be written in the files subdirectory. The reason these many *.files files are written is so if an individual wfsc image is bad or corrupt, it can be removed from the appropriate *.files file (eg 182-184_gstar_19.files) and the data set reprocessed easily.

Step 2) field_process_set

IDL> field_process_set, /SILENT, /DISPLAY, /FORCE

A dialog box will popup and you can choose the *.list file to process (eg bs9126.list, created by field_make_files). This routine calculates a quick and dirty estimate of the primary/secondary misalignment and writes a data file that can be read by Andrew's Mathmatica routine, which calculates a robust misalignment value. /SILENT supresses alot of intermediate output such as individual Zernike measurements. /DISPLAY controls whether to display the 3D results plots at the end - it doesn't not control the display of individual wfsc frames.

Hint: If it prompts you for fits file names, move all the .fits files down into the wfsc subdirectory.


  • rfbg_new.results Output of the field aberration translated into PSF Tip-Tilt to be applied to the secondary mirror.
  • rfbg.dat For each star: gs, x_field, y_field, angle, z4, z5, z6, z7, z8, astig_total, coma_total, rms
  • rfbg_all.dat For each star: gs, z4, z5, ....... z22
  • rfbg_scale.dat For each star: angle, focus_scaled, z5_scaled, z6_scaled, astig_scaled, coma_scaled, rms_scale
  • rfbg_on.dat For each on-axis star (before and after gs#): gs, focus, 0-astig, 45-astig, x-coma, y-coma

Output looks like this (trimmed down):

             Measured bi-nodal astigmatism

              From 45 Astigmatism Measurement
                  On-Sky Arcseconds
          Tip =   4.3", Delta IE =  -4.3"
         Tilt =  24.9", Delta CA = -24.9"

              From 0 Astigmatism Measurement
                  On-Sky Arcseconds
          Tip =  -3.3", Delta IE =   3.3"
         Tilt =  27.3", Delta CA = -27.3"

I suggest Tip = 0, Tilt = 25


 => Field Data Results
             Measured bi-nodal astigmatism

              From 45 Astigmatism Measurement
                  On-Sky Arcseconds
          Tip =  19.4", Delta IE = -19.4"
         Tilt =  16.9", Delta CA = -16.9"

              From 0 Astigmatism Measurement
                  On-Sky Arcseconds
          Tip =   7.4", Delta IE =  -7.4"
         Tilt =  18.0", Delta CA = -18.0”

I suggest Tip =15, Tilt = 17  (or none at all…might be in the noise)

Field Aberration Data Implementation

  • Step 1: Convert the M2 Tip-Tilt corrections into X,Y,RX,RY position corrections
    • Go to "Control" section of PSFGUI.
    • Under manual pointing, select OPE "M2" (not "M1M2").
    • Enter the Tip and Tilt values in arcsec
    • Press "Send" to apply manual pointing.
    • Go to the "Secondary" section of PSFGUI.
    • Record the values in "Manual Pointing Offsets" (i.e. RFBG X=-1.277 Y=0.0 Z=0.0 RX=0.0 RY=-245.5) (LFBG X=-0.868 Y=-0.766 Z=0.0 RX=147.3 RY=-166.939)
    • Put the Tip and Tilt back to 0,0, and press "Send" to apply the manual pointing.

  • Step 2: Apply the M2 Position corrections for the PSF lookup tables for all Gregorian focal stations
    • ssh tcs@tcs1 (login to TCS machine where PSF runs)
    • cd /lbt/data/config/tcs/PSF (The directory for "public" / "astronomer" config variables for PSF subsystem.)
    • ls -ltr DXSMLUCIFERCollimation* (show the recent history)
    • cp -p DXSMLUCIFERCollimation.dat DXSMLUCIFERCollimation.20220413.dat (save the previous file in a name that matches its modification date)
    • edit DXSMLUCIFERCollimation.dat to sum your manual pointing offsets into the "Offset collimation" line.
    • ./propagate_DXSMLUCI.csh (copies the file to all other Gregorian focal stations, except LUCI ARGOS)
    • edit DXSMLUCIFERACollimation.dat (it isn't handled by the auto-propagation script)
    • press "Initialize" on Secondary section of PSFGUI to reread the LUTs
    • cp -p DXSMLUCIFERCollimation.dat DXSMLUCIFERCollimation.20220910.dat (save the new file in a name that matches its modification date)

Field Aberration Data Background

(adapted from Andrew Rakich, 2022)

The original active optics systems, from the NTT to the great telescopes of the 90’s had a design flaw in that they relied on one wavefront sensor with which to measure the alignment state of the main optics (basically, congruity of optical axes and correct spacings) as well as mirror shapes. It was assumed that because “decenter astigmatism” was tiny, astigmatism could be discounted and the wavefront sensor could find a correct telescope alignment state by measuring coma, spherical aberration and focus (as well as other low-order terms such as trefoil arising from optic deformation). In particular, it was thought that any measured coma could be corrected with decenter without consequence. In the mid-70s R. Shack and K. Thompson had shown that while the alignment state of a two-mirror telescope is degenerate in decenter and tip/tilt for coma, this is not the case when the astigmatism field is considered, and in fact any alignment state other than congruence of the optical axes of the two mirrors gives rise to new field-astigmatism terms that vary linearly with field angle and grow in proportion to the optical misalignment. It wasn’t until the early 1990’s that Bhatia (1995, TNG Tech Report #43) first referenced Shack and Thompson's work in the context of modern telescope alignment. B. McLeod, who picked up on Bhatia’s work, first put linear astigmatism firmly on the map for astronomical telescope engineers with his paper on wide-field telescope alignment.

Pupil Wobble Measurement for the Off-Axis S-H Wavefront Sensor

Pupil Wobble Data Collection and Analysis

Pupil Wobble - Introduction

We adjust the Tertiary Mirror tip-tilt in order to achieve the proper angle of the chief ray, and thus the proper pupil position in the AGW and Instrument. See BGTechProcedures for the optical explanation of why we are doing this adjustment to make the incoming chief ray parallel to the instrument rotator axis.

The IDL routine pupil_collect (click to view description) collects a set of SH WFS Pupil Wobble data by manually (via IDL) collecting 4 (more if requested) SH WFS images at 4-6 different instrument rotator angles. The rotator angles are defined in the file
;    angle = [0., 60., 120.0, 180.0, 240.0, 300.]
;    angle = [0., 60., 120.0, 180.0]
    angle = [180.0, 120.0, 60., 0.0]

You can comment/uncomment the appropriate lines, and even add angles to the angle "vector". Save the file, and then stop and restart IDL. Interpretation of the plot may be easier with smaller angular offsets (more angles).

Pupil Wobble - Data Collection On-sky

Developed by DLM and JMH in September 2016. This is most efficient with two people doing it (and one of them should be Doug). This procedure can tolerate some clouds and bad seeing, but the data is cleanest with consistent good seeing.

  • Send an ACTIVE preset to collimate on-axis (typically a Persson star)
    • Check that the preset did NOT include a "hotspot" which positions the on-axis guide star away from the rotator center.

  • ssh lbto@obs1 (or obs2)

  • Start first with IDL on LFBG, but can be run in parallel on RFBG using another IDL session. Start IDL in a working directory like: /home/lbto/data/20170205_lfbg/

  • press "stop WFSing" on left GCSGUI after you are decently collimated
% cd ~/data
% mkdir -p 20180525_lfbg
% cd 20180525_lfbg
% idl_agw
IDL> iif_register, LFBG   (or , /TCS if authorized monocular LUCI@LFBG)
IDL> pupil_collect
  • Note that wfsc images taken by IDL via gcsclient are collected in a different directory /lbt/data/share/tcs/lbto.20170205
    (in 201909, this is the path for obs2-obs4 (CentOS), but not the path obs1 (Fedora) - see IT 7836)

  • Iterate the direction and axis of the M3 tip-tilt adjustment (below) to minimize the wobble to the smallest circle with a goal of 1-2 pixels. See the next section for the semi-automated analysis of the wfs images.

Other IDL command line arguments for pupil_collect

  • Change the default exposure time: EXP=10.0 (for a 12th mag star)

  • When there is not a live preset: /OPEN
    • /OPEN means move the rotator with a low-level IRC command when telescope is not on a live preset. NOT /OPEN means use normal OffsetTelescope command with 0,0,Delta_Rotator_Angle arguments.

  • There is (or there used to be) also an option to leave the WFSing running so that GCS is collimating and taking the wfs images.

Pupil Wobble - Analysis

The execution of the pupil_collect routine writes two files, pupil_"time".files and pupil_"time".wobble. The first file has a list of the collected wfs images. The second has the file names as well as the measured X,Y pupil center in pixels. The file pupil_"time".wobble looks like:
lbto@obs2:16 % more pupil_10:19:15.wobble
# Shack-Hartmann Pupil Wobble data
# x_center   y_center   rotangle    imagename
    385.55    214.49    325.32   left_wfsc000019_dd.fits
    386.36    215.91    268.48   left_wfsc000020_dd.fits
    384.59    215.42    211.87   left_wfsc000021_dd.fits
    383.59    214.00    515.65   left_wfsc000022_dd.fits

Use /lbt/lbto/supportscripts/MetrologySupport/ to plot the all the .wobble files (new on 20190913). The black curve is the most recent set (black, red, green, navy, cyan, ...). Each point is labeled with the Instrument Rotator Angle in degrees (3rd column in the file). You want the wobble to be as small as possible (with a 1-pixel goal that we don't always achieve). See the next section for advice on which way to move M3.

Plotting Details

Note: "" is a Python 3 script, so will need to run on a Fedora machine.

When plotting all of the wobble sets is too confusing, use:
/lbt/lbto/supportscripts/MetrologySupport/ -n 3 to plot the last 3, or
/lbt/lbto/supportscripts/MetrologySupport/ -n 5 -b 2 to plot the last 5 without the last 2.

/lbt/lbto/supportscripts/MetrologySupport/ -n 3 -s DX -a to plot on a fixed scale for the DX = RFBG side. (It plots whatever is in your working directory, but the -s DX helps out with plot defaults and title.) uses the following syntax for making xmgrace plots. To plot the file pupil_"time".wobble use your favorite graphics routine, or use xmgrace:
$ xmgrace -par ../pupil_wobble.par -block pupil_10:19:15.wobble -type xyz -bxy 1:2:3 &

Or for two sets:
$ xmgrace -par ../pupil_wobble.par -block pupil_10:19:15.wobble -type xyz -bxy 1:2:3 -block pupil_10:37:38.wobble -type xyz -bxy 1:2:3 &

This plotting has been tested for up to 10 wobble sets (be confused at your own risk), but only the first 6 sets get the numerical labels. If you don't get any numerical labels at all, you may be working in a subdirectory where ../ is not the path to the xmgrace parameter files which normally live in /home/lbto/data/lfbg_pupil_wobble.par .

Pupil Wobble - Moving the Tertiary

  • Make an adjustment of the M3 tip-tilt angle (typically 100-200 arcsec), and then make another measurement
    • record both the M3 global offsets as well as the absolute M3 tip,tilt,selector angles
    • resend ACTIVE preset as needed to stay collimated (every half hour)
    • use /lbt/lbto/supportscripts/MetrologySupport/ -s SX -p [tip] -t [tilt] which does the following automatically:
      • Block sending centroids to PCS (on the GCSGUI Guiding Control page)
      • Move M3 Tip/Tilt in Global Offset (on the PSFGUI M3 page)
      • Recover pointing with IE/CA corrections (from PTPADDLE on pngui)
      • Resume sending centroids to PCS
(This is the 20190913 corrected version of an email from 20170903.)
     This is what I get for pointing corrections to compensate
M3 motions. This is based on our corrections from 20170902 UT.

SX LUCI Focal Station Angle =+26
For SX Tip   dIE= (Tip/12)*sin(FSA)  dCA= (Tip/12)*cos(FSA)
For SX Tilt   dIE= (-Tilt/18)*cos(FSA)  dCA= (Tilt/18)*sin(FSA)

DX LUCI Focal Station Angle=-26
For DX Tip   dIE= (-Tip/12)*sin(FSA)  dCA= (-Tip/12)*cos(FSA)
For DX Tilt   dIE= (-Tilt/18)*cos(FSA)  dCA= (Tilt/18)*sin(FSA)


  • Iterate with another round of pupil_collect

Pupil Wobble - Which Way to Move Tertiary? (under development)

The measured pupil centers plotted with xmgrace above should make a quasi-circle (polygon) in wfs pixel space since we moved the instrument rotator through 360 degrees of rotation. When you are finished, the size of that polygon should be 1-2 pixels, but it could well be 10-20 pixels when you start. This section attempts to give advice about which direction to tip-tilt the tertiary to make the search more efficient than a random walk.

Warning: AGw2 has shown historically to converge to a line rather than a small circle. (We don't understand why, but flexure always comes up in the conversation. See also IT 8184 about loose AGW mounting bolts.)

How much to move M3

  • The amount to tip-tilt the tertiary is about 80 arcsec per wfs pixel that you want to move. (We measured more like 25 arcsec per wfs pixel on 20200828, so lets say this number is uncertain. Maybe Tip and Tilt have different scales? See 12 vs 18 in the previous section. Probably Tilt needs a larger number of arcsec/pixel than tip.)

Which way to move for LFBG

  • If the 0/360-degree point (rotator angle) is on the right (upper right) side of the polygon, then you need +Tip on SX M3 to move that point left (lower left) and decrease the size of the circle.
  • If the 0/360-degree point (rotator angle) is on the top (top left) side of the polygon, then you need -Tilt on SX M3 to move that point down and decrease the size of the circle. (still need to confirm this on another data set)

Which way to move for RFBG

  • If the 0/360-degree point (rotator angle) is on the right (upper right) side of the polygon, then you need +Tip on DX M3 to move that point left (lower left) and decrease the size of the circle.
  • If the 0/360-degree point (rotator angle) is on the top (top left) side of the polygon, then you need +Tilt on DX M3 to move that point down and decrease the size of the circle. (still need to confirm this on another data set)

Automation of the direction determination

In Sep 2021, John is working on more automated analysis of the pupil wobble plots. The 20210901 version of computes the relative angle of the pupil center at the different rotator positions relative to the mean pupil center of the wobble. The temporary output looks like this:

/lbt/lbto/supportscripts/MetrologySupport/ script version of 01-Sep-2021
ls -1t *.wobble

filename               Xavg     Yavg     Radius    Angle1 (rms)     Angle1 (rms)   pts
pupil_06:33:44.wobble  380.555  269.293 12.49461   62.441 (212.2)  -87.091 ( 64.7) 4
pupil_06:20:44.wobble  376.618  266.570 16.12693  -76.081 (259.6)  -46.304 (186.9) 4
pupil_06:00:22.wobble  378.327  269.235 10.64723   61.319 (210.3) -107.639 ( 32.0) 4
pupil_05:48:20.wobble  379.037  270.777  8.61351   44.394 (232.4) -100.279 ( 56.8) 4
pupil_05:37:40.wobble  377.653  270.595 14.02867   28.331 (225.7)  -93.556 ( 48.9) 4
pupil_05:28:58.wobble  377.330  271.373 11.97179    4.592 (206.6)  -77.722 ( 44.5) 4
pupil_05:18:44.wobble  376.743  269.727 14.35255   62.430 (130.0)  -54.770 ( 50.3) 4
pupil_05:05:31.wobble  376.028  272.625 18.23065   -6.997 (201.7)  -87.863 ( 54.1) 4
pupil_04:51:38.wobble  375.415  271.765 16.56717   54.219 (141.5)  -73.624 ( 55.1) 4
pupil_04:11:49.wobble  377.260  271.045 18.07894   78.933 (142.6) -132.133 ( 38.3) 4

xmgrace -geometry 930x730   -par ../rfbg_pupil_wobble.par -legend load -block pupil_06:33:44.wobble -type xyz -bxy 1:2:3 -block pupil_06:20:44.wobble -type xyz -bxy 1:2:3 -block pupil_06:00:22.wobble -type xyz -bxy 1:2:3 -block pupil_05:48:20.wobble -type xyz -bxy 1:2:3 -block pupil_05:37:40.wobble -type xyz -bxy 1:2:3 -block pupil_05:28:58.wobble -type xyz -bxy 1:2:3 -block pupil_05:18:44.wobble -type xyz -bxy 1:2:3 -block pupil_05:05:31.wobble -type xyz -bxy 1:2:3 -block pupil_04:51:38.wobble -type xyz -bxy 1:2:3 -block pupil_04:11:49.wobble -type xyz -bxy 1:2:3

You want to watch the relevant Angle - either Angle1 or Angle2 - whichever has the lowest rms. Angle1 is appropriate when the rotator angles increase clockwise around the wobble center on the plot. This Angle (a difference averaged over all rotator angles) should tell how much the pupil location at each rotator angle is rotated from the top of the plot (really want it relative to the Tip axis, but not yet corrected for focal station offsets). Beware that both Radius and Angle get squirrely at small wobble radii because the noise in the pupil center determination dominates the size of the wobble.

Pupil Wobble - Wrap-up

  • Finish
    • store final M3 Absolute Tip-Tilt values in (on tcs1) /lbt/data/config/tcs/OSS/positions.conf
    • update pointing models if you made a significant adjustment
    • update GCS pupil positions if you are not taking transformation data immediately (otherwise the transformation data gives a better fit to pupil positions across the field).
    • Clear your M3 Global Offsets when OSS has been restarted to read the new Absolute values.
  • Document
    • Use "Save as" in xmgrace to save a JPEG plot (the plot seems to be larger on robs compared to obs1).

Zernike Scale Factor Measurements

Zernike Collection

The IDL routine zernike_collect (click to view description) collects a set of zernike data by collimating the telescope, applying a requested amount of a given zernike mode to the mirror (primary or secondary), collecting three wavefront camera image with out sending corrections to the TCS, removing the mode applied earlier and then collimating again. This four step process is repeated for as many modes as are listed in an input file that the user is queried for. This can be done on any star whose brightness is suitable for wfs images.
% cd ~/data
% mkdir -p 20141211/zern
% cd 20141211/zern
% idl_agw
IDL> iif_register, RDG
IDL> zernike_collect

A repository of files containing the modes and amplitudes to apply lives in ~/idl/wfsc/zernike/lists. A file looks like:
# Type of act. opt, zern # magnitude, ...
4   500.
5   500.
6   500.

A file named zern_"focal station".log (e.g. zern_rdg.log) is written with a list of mode, amplitude, wfsc numbers and measure amplitude.
#Title Zernike Scale Factor Data
#Date 20141117
#Type zernike
#Station RDG
#Data_Dir ../wfsc
#Source IDL
#Labels Zern     Amp      wfsc#     scale      Avg     Factor        Measured
   0    0    1          1.0        53      
   4    500  2-4        1.0       358   358   358   358   358      
   0    0    5          1.0       -25      
   0    0    5          1.0       -25      
   4   -500  6-8        1.0      -417  -417  -417  -417  -417      
   0    0    9          1.0      -171 

This file can be read by zernike_process_set, which calculates the scale factors relating the actual amplitude applied to the telescope mirror and the amplitude measured by the Active Optics. These scale factors should be used by the GCS in its Active Optics calculation and are specified in /home/telescope/TCS/Configuration/GCS/"instrument"_"side"_RM_13.cfg (e.g. MODS_R_RM_13.cfg).

Zernike Analysis

To analyze the zernike data, the .log file written by zernike_collect must be first processed to write a whole slew of intermediate files in a subdirectory *files*
% cd ~/data/20141211/zern
% idl
IDL> zernike_make_files

The IDL routine zernike_process_set (click to view description) reads in the file written by the IDL routine zernike_make_files (see above) and processes the wfsc images. The format of the .list file needed by the zernike data analysis routine, zernike_process_set is:
# Date, focal station, files directory
     000001-000001_z0.files      0         0.    1.00000e+00
     000002-000004_z04.files     4       500.    3.60000e+04

where the .files files listed in this .list file (e.g. 000001-000001_z0.files) are also in the *files* directory.

To analyze the zernike data:
% cd ~/data/20141211/zern
% idl
IDL> zernike_process_set, /GAINS, /LATTER

Zernike Rotation Measurements

(This section seems to have gotten lost from the wiki. ?? Was it ever here?) Use zernike_collect as described in the previous section.

Zernike Rotation Analysis

These instructions are to analyze wfs images from the off-axis wavefront sensor (used on-axis) to determine the proper rotation angle from wfs space to primary mirror space.

(these instructions were provided by Doug Miller in an email on 20171006, and copied to wiki by John Hill)

login to LBTO account on one of the obs* machines

% cd data
% mkdir rot_angle
% cd rot_angle

% idl

IDL> iif_register, LPOL, /TEST

*  => LEFT Focal Station LPOL: LPOL

==> /TEST means you will not send any request to the IIF: for safety

IDL> collimate_make_file, repo='20170920', range=[850,969]
=> 120 wfsc filenames written to range.files

==> repo=\x91***\x92 give the dated directory in /Repository/, + /GCS
==> range is the range [start, end] to write to .files file
==> file is written in ./files directory

IDL> collimate_multiple_list

===> pop up box, click on range.files
===> will process files list and output (a lot) of info
===> creates file ./results/range_zern.dat

IDL> exit

You now need to plot columns in the file ./results/range_zern.dat

% cd results

The file looks like:
# Type Sext
# Zernike Total
#     date/time              Rotator         Guide Probe              Pupil            RMS    Focus  0 Astig 45 Astig X-Coma Y-Coma  0-Tref 30 Tref Sphere
#                             Angle         x           y      x center    y center    Sent    Z4      Z5   Z6      Z7     Z8    Z9     Z10     Z11
#   (1)                    (2)         (3)         (4)         (5)         (6)     (7)     (8)     (9)   (10)    (11)    (12)    (13)    (14)    (15)    (16)  etc
2017-09-20T10:35:03.386       43.66     -0.05        0.02    154.45      220.15    1422     567    -330   1608    -736    1030 etc
2017-09-20T10:35:16.478       43.47     -0.05        0.02    154.45      220.15    1373     741    -199   1484    -866     980  etc
2017-09-20T10:35:29.271       43.27     -0.05        0.02    154.45      220.15    1469     718    -505   1575    -694     921  etc

The header tells you which column is which zernike.

DLM uses xmgrace to plot this file.

% xmgrace -block range_zern.dat -bxy 1:9 -bxy 1:10 &

===> note, -bxy 1:11 -bxy 1:12 for coma plots

To plot Z5 and Z6. xmgrace will create an x-axis with time stamps. To do this, click on the top menu line \x93Plot\x94 -> \x93Axis Properties\x94 (See jpg)

Click (Tick Properties box) click Format box and choose HH:MM:SS. Then click Apply at the bottom of the popup box.

The graph will look something like:

The black line is the first data set (cols 1:9) and the red is the second (1:10)

This plot used the wfs_rotoffset of 9.0. To change this and reprocess the data edit the file /home/LBTO/idl/wfsc/agw/ Edit the section labeled RPOL or LPOL. The IDL values you may need to change are (corresponding GCS parameters have different names):

            agw_params[i].wfsc.rot_offset = 9.0
            agw_params[i].wfsc.pupil_x_on_axis = 400.6
            agw_params[i].wfsc.pupil_y_on_axis = 225.6
            agw_params[i].wfsc.lenslet_x_center = 266.
            agw_params[i].wfsc.lenslet_y_center = 111.5

To apply these changes you exit IDL and start again.

% idl

IDL> iif_register, LPOL, /test (or RPOL)
IDL> collimate_multiple_list, /force

===> /force makes the routine recalculate the WF. Otherwise it reads .sav files, without the changes applied

Active Optics Tools

Building a Reconstructor

The reconstructor matrix used to determine the wavefront via the AGw is built by analyzing the synthetic wfsc images created by Andrew Rakich using Zemax. The steps are:

  • Andrew creates the needed wfsc images (zernike modes 2 through 22 and an unaberrated image)
  • Convert the text files from "unicode23" to "Western MacOSX ' form vie "textedit
  • Read the text files, pad the image to with 100 rows and columns, convolve with a Gaussian, include the required Data Dictionary values in the header and write a fits file.
  • Run "recon_create_matrix" routine to evaluate the given list of wfsc images, create the interaction matrix with the centroid values, use single value decomposition to find the inverse matrix, determine the reconstructor matrix and write the recon matrix and centroid offset fits files.
  • Set the new reconstructor directory as the default reconstructor in

Detailed instructions

Catalog Tools

Create Catalogs from online catalogs

The catalogs on the mountain live in the directory /lbt/catalogs.

Please create new catalogs in your directory (ie /home/LBTO/idl/catalogs/Ostar) and once they are built and you have confirmed that they are correct, then add them to the catalog svn repository. For example:
% cd idl/catalogs
% svn status       (get a listing of new files that are not in the repository)
% svn add Ostar/catalogs/Ostar_1.catalog Ostar/images/agr/Ostar_1.agr Ostar/images/jpg/Ostar_1.jpg
% svn commit

These new files must then be updated in the /lbt/catalogs directories via:
% ssh telescope@obs2
% cd /lbt/catalogs
% svn update

Stone Field Catalogs

Instructions to create Stone Field catalogs

Catalogs from Target Coordinates

Instructions to create catalogs give target coordinates

Catalogs for Regions on Sky

Instructions to create catalogs for regions on sky

-- DougMiller - 22 Dec 2010
Topic revision: r78 - 18 Oct 2023, JohnHill
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback