Calibrations and Defaults

GPI requires a number of calibrations to operate, some of which need to be updated on a regular basis. These are described below along with notes on how to generate/update calibration products. In addition, gpilib allows for the saving of default settings for a variety of mechanisms to aid in quick system alignments and the generation of calibrations.

AOC Calibrations

The AOC subsystem requires calibrations for the wavefront sensor (WFS), as well as reference centroids for closed loop operation. The AOC calibrations and parameters are described in detail here: AOC Calibration files and parameter values

WFS Darks

The AO WFS requires up to date dark frames for each camera frame rate. These must be updated at least once per hour and more frequently immediately after the MEMS DM is first powered on. For more information see: WFS_DARK_X. To generate new darks, simply turn off the light (turn off the laser if using the ASU or close the OMSS shutter if getting light from the telescope or TELSIM) and then use the ult_measure_darks command:


LOOPS MUST BE OPEN before you do the following. After you are done, don’t forget to check that the light is back on before attempting to reclose.

;If using ASU:
IDL> tlc_move_source,sc_att=60,sc_pow=0
;If using Telescope/TELSIM:
IDL> tlc_move_source,shutter='closed'
IDL> ult_measure_darks

This sequence is also wrapped by utility function ult_take_ao_darks, which shuts off the light, calls ult_measure_darks, and then restores whatever light source was in use:

IDL> ult_take_ao_darks


The Instrument Sequencer Align&Calib routine will automatically take AO darks for you.

WFS Flats

The AO WFS also requires flat fields. There is currently no method for updating these flats as they were generated before the WFS was integrated into the AOC. If the flats ever become corrupted restore them from the backup of the AOC config directory. See WFS_FLAT_X for details on file locations.

AO Reference Centroids

The AO reference centroid schema is described in detail in: Reference Centroids. In general, you will only be updating the base (measured) reference centroids and the apodizer specific offsets. The base references should be updated daily. This is done by setting up a pinhole with the spatial filter, flood illuminating the AO WFS, issuing the AOC measure references command, and then selecting the measured reference centroids:


LOOPS MUST BE OPEN before you do the following. After you are done, don’t forget to check that the pinhole was successfully removed and attenuation turned down before attempting to reclose the loops.

IDL> ult_task_make_pinhole,att0=att0,sfsize=sf_size,cal_exit=cal_exit,before_state=before_state,drkcrnstat=drkcrnstat
IDL> ult_measure_refs
IDL> rtc_command_select_references,/measure
IDL> ult_task_breakdown_pinhole,att0,sf_size,cal_exit,before_state=before_state


The ult_measure_refs command has to first take off whatever the prior refs are so that it can measure the new ones. It leaves the system in a state with no refs, which would completely destabilize if you tried to close loops then. The subsequent command rtc_command_select_references is thus essential to activate the new refs. Note that if you have any offsets applied and wish to keep them then you should enter rtc_command_select_references, /measure, /off. The ult_measure_refs command helpfully prints to the IDL window a reminder of these options when it finishes.

Apodizer specific reference offsets are typically derived from the results of speckle nulling. See Speckle Nulling for details.

The last command in the above sequence, ult_task_breakdown_pinhole, simply restores the pinhole mechanism to whatever its prior state was before the call to ult_task_make_pinhole.

AO Tip/Tilt Flat

For historical reasons this called a ‘flat’, but it’s really just the zero point position that the tip tilt mirror will go to whenever you request a flat tip tilt or issue a flatall command. This is documented here mostly to clarify that it’s a very different thing from e.g. an AOWFS flat.

Disclaimer: This only has effect in IDL and there is no equivalent in the IS or the real time controller code. In the real time code all you can do is set the mirror to bias, not to flat.

This is updated using ult_task_point. This happens routinely as part of ult_sysalign and is not something that typically needs to be done manually.

DM Flats

DM flats are used in a variety of calibration and alignment procedures where the AO loops cannot be closed (for example when arbitrary shapes must be placed on the mirrors). They represent the best static flattening shapes for the mirrors and must be updated on a regular basis(weekly or daily). In addition, the woofer lab flat is used to apply a pure focus on the woofer during closed loop operation. DM flats are saved using the function ult_save_dm_flats, which is wrapped by a helper function ult_measure_dm_flats. This:

  • Saves a zero shape to the woofer lab flat
  • Closes all loops
  • Saves the closed loop shape to the woofer system flat
  • Reads in the woofer system flat, reconstructs the focus term only and saves this to the woofer lab flat
  • Re-closes all the loops and saves the closed loop shape to the tweeter system flat

For more discussion on lab vs. system flats see AOC Calibration files and parameter values and the AOC users’ guide (

CAL Calibrations

CAL Darks

How often these should be taken is not well characterized yet.

To take CAL Darks, you can either:

  • In the CAL Server Control GUI, press the ‘Take Dark Exp’ button (located just over halfway down the giant stack of buttons). Before you do this, make sure the filename field next to the button is blank, so it will use the default filename.

  • In IDL, enter the command:

    tlc_command_cal_take_darks, '""'

    The blank string there has the same meaning as above, to use the default filename for the saved dark.

CAL Flats

We don’t have a good way to take these right now unfortunately.

CAL Reference Centroids

Also not taken regularly because we are not using the LOWFS beyond tip-tilt.

There are a variety of other more esoteric CAL calibrations which are likewise not a concern in the current state of things.

IFS Calibrations

The IFS requires darks, flats, bad pixel maps and wavelength and polarimetry solutions in order to produce spectral and polarimetric data cubes. See the GPI pipeline documentation. gpilib contains a number of helper functions to aid in the data collection for these products. See IFS Calibration Functions.

However, these are mostly leftovers from earlier in the GPI development process. These days it is preferential to take IFS calibrations using the template calibration sequences in the GPI library section of the Observing Tool.

Coronagraph Calibrations

The GPI Apodized-Pupil Lyot Coronagraph (APLC) consists of three elements: the apodizer (pupil plane mask; PPM) in the AO system, the Focal Plane Mask (FPM) in the CAL, and the Lyot stop in the IFS. The FPM is re-aligned regularly as part of ult_sysalign, and you can run that alignment at any time. The Apodizer and Lyot Stop, on the other hand, are kept in alignment via open-loop models, which run whenever the system is tracking. Their zero points must periodically (but rarely) be updated. Both elements are aligned to the MEMS plane via helper function pupalign.

FPM Alignment

The FPM alignment may be peformed either via alignfpm_and_centerpin or via the Instrument Sequencer Align&Calib routine.

Physically the result of this process is countersteering the AOWFS PnC mirrors, such that the optical ray which falls on the center of the AOWFS corresponds (on the other side of the dichroic split) to the infrared ray which passes through the center of the FPM. Thus the result of an FPM alignment is an updated set of

Apodizer Alignment

The apodizers are aligned with the function ult_task_align_apod. This function requires a pupil-viewer dark, so you must either load in a recent one, or take a fresh one with the Blank Lyot in place:

IDL> tlc_move_ifs,pupil = 'deploy',lyot='blank',errout=errout
IDL> tlc_move_cal,/exit,/open
IDL> tlc_take_exposure,imageout=pupdark
IDL> res = ult_task_align_apod(pupdark,band=apod)

where apod is the name of the apodizer. See validate_apod_name for a list of available apodizers. The output res is a 2x1 array containing the absolute filter wheel settings for the apodizer (these are offset in mm and rotation in degrees). These can then be entered in the configuration file on the TLC($TLC_ROOT/config/CONFIG.PpmAssembly) in the PPM_FILTER_POS lines.


The configuration files are version controlled and should only be edited by users who can also check in the changes.

This is an infrequent calibration to update the positions in the config file (perhaps once a semester). However the positions are checked and validated as part of ult_sysalign. This will alert you if something is far out of tolerance.

Lyot Alignment

The Lyot stops are aligned in a very similar fashion to the apodizers (above), using the function ult_task_align_lyot. This function also requires a pupil-viewer dark, but you can use the one you took for the apodizer alignment, if you are doing both.

IDL> res = ult_task_align_lyot(pupdark=pupdark,lyot=lyot,/retstruct)

where lyot is the name of the Lyot stop. See validate_lyot_name for a list of available stops. The output res is a structure returned by pupalign, whose field pncval contains the CAL-IFS centering settings to align the Lyot (2nd and 3rd elements of the array). Alternatively, you can query the current centering targets and datum positions (the centering offsets will be the difference of these) via functions tlc_query_cal_pnc and tlc_query_calpnc_offs, respectively. These can then be entered in the configuration file on the TLC ($TLC_ROOT/config/CONFIG.IfsAssembly) in the LYOT_MASK_POS lines.

To simply measure the alignment, and not actually try to apply any correction, you can call ult_task_align_lyot with the keywords /checkonly, /nomove. This will display the offsets on screen (as part of the IDL console text output) in units of pupil viewer pixels.


The configuration files are version controlled and should only be edited by users who can also check in the changes.

Again, this is not a frequent calibration.


gpilib contains a number of setter and getter functions that store and retrieve default values for various GPI mechanisms. These defaults are often used in various calibration and alignment procedures and are, for the most part, kept up to date automatically. Below is a list of all of the functions. In each case there are two associated functions: load_* and save_*. For details see Configuration Functions.

Name Notes
_best_tt AO tip/tilt zeroing values (in mas). Since these are dependent on the AO PnC and inputfold settings, they must be updated whenever those values are changed. See ult_task_point.
_default_apod Used to store override positions [x-offset (mm), rotation (degrees)] for the PPM filter wheel to touch up the defaults stored in the TLC configuration. Used when tlc_move_apodizer is called with the /default flag and by tlc_obsmode.
_default_cal_pnc_pc CAL-IFS PnC mirror defaults [ x pointing (mas), y pointing (mas), x centering (mm), y centering (mm), focus (mm)]. In addition to the current default there are also storage slots for all of the different Lyot stops which can be accesed with the lyot keyword.
_default_inputfold Inputfold defaults [x (mm), y (mm)].
_default_pnc_pc AO PnC mirror defaults [ x pointing (mas), y pointing (mas), x centering (mm), y centering (mm), focus (mm)].
_sfpos Spatial filter default position [x (mm), y (mm)]. See tlc_command_sf

The specific file that the defaults are written to and read from is determined by the currently set operating mode in the IDL session. For details see Operating Modes.