Quick Start Guide

This section is intended to get you up and running with gpilib as quickly as possible, either for analysis of AO data or for actually running the instrument.

gpilib for Analysis

Assuming you are running gpilib on your own computer and simply want to use some of the built-in analysis and visualization functions, the setup is very simple.

  1. Make sure that gpilib is in your IDL path.

  2. Start IDL

  3. In the IDL session, run simaoc:

    IDL> simaoc
  4. Load the common block:

    IDL> common gpi_globals

You are now ready for data analysis.

gpilib for Controlling GPI

This section is for controlling the instrument, either locally or remotely, and assumes you have access to the Gemini VMs. It lists the basic series of steps that allow you to take science images in a spectral, coronagraphic mode with links to detailed information for each step. Note however, that GPI is a complex and sometimes finicky system. If you do not fully understand a step, or the conditions under which is should be run, DO NOT execute it until you have read the background material. Similarly, do not deviate from the steps in this guide unless you know exactly what you are doing.


When using this guide, it is recommended that you open links in new tabs so as not to lose your place in the procedure.

  1. Connect to the GPI control VNC session. See Connecting to a VNC Server via SSH Tunneling.

  2. Verify that you have all of the windows you need to run GPI (at least the Control IDL session, AOC dispraw, and the TLC GUI). See Working Setup for details.

  3. In the IDL session, load the gpi_globals common block:

    IDL> common gpi_globals

    See Common Blocks for details.

  4. Make sure that the system is ready for use (not interlocked).


    Figure: Main TLC GUI. To operatue GPI, all heartbeats must be ‘Good’ and interlocks must be off. Note that some Health entries may appear as ‘Bad’ if the previous command in that assembly generated an error. As long as the Heartbeat is good and the State is idle, the assembly is ready for use.

    You should also note whether any components you might need are currently simulated (i.e., the pupil viewer and polarizer prism slide). For example, in the above screenshot, the pupil viewer, polarizer, and ASU SC laser are all in simulate mode as indicated by the red ‘SIM’ to the right of each. The Art Src (Supercontinuum source) is kept in SIM mode when the laser is off and is automatically taken out of SIM by ult_sysalign. Finally, make sure that the One Wire assembly is ‘Logging to file’ (indicated to the right of the One Wire button), and that there are no current errors in the Message box.

    You should also ensure that all open loop models are turned on, by looking in the AO and Track assemblies for the word ‘YES’ to the right of the ‘Apply Open Loop Model’ buttons (or alternatively, checking for ‘OL’ indicators in gpiDiagram) :


    Figure: AO Assembly and Track Assembly GUIs. Open Loop Models must be applied (set to ‘Yes’) for the AO Spatial Filter (AO Assembly) and AO WFS and CAL-IFS Pointing and Centering (Track Assembly).

  5. Run ult_sysalign. See System Alignment for details. If you do not know the exact settings you want, you should use the /guide flag with ult_sysalign:

    IDL> ult_sysalign,/guide

    This will ask you a series of questions and configure the system based on your answers. In general, all of the defaults are sane (defaults can be selected by just hitting enter).


    While the pupil viewer is simulated and extracted, do not attempt to check apodizer and Lyot alignments.

    If you’re only interested in working with the AO system, then you can stop after the system has been aligned to the CAL. If aligning all the way to the IFS, you must select an observation mode (obsmode). Available modes are:

    • Y_coron
    • J_coron
    • H_coron
    • K1_coron
    • K2_coron
    • H_starcor
    • H_LIWAcor
    • Y_direct
    • J_direct
    • H_direct
    • K1_direct
    • K2_direct
    • NRM_Y
    • NRM_J
    • NRM_H
    • NRM_K1
    • NRM_K2
    • DARK


    If you align all the way to the IFS, assuming no errors, the procedure will exit with all loops closed, the CAL exit shutter closed, and the AO SF open. Be aware the loops are closed and the spatial filter is full open.

    At the end of this process you will have a fully aligned system with all loops closed and all PnC mirrors tracking. Make sure that everything looks sane before proceeding.


    Figure: This is a happy DM. If your dispraw doesn’t look approximately like this (minus the spiders if you are not using the TELSIM) then something went wrong. Then you have a sad DM.

  6. If an error occurs during execution of ult_sysalign, DON’T PANIC. Your first goal is to ensure instrument safety. Attempt to zero the mirrors by issuing IDL command:

    IDL> zeroall

    If any loops are still closed you must open them first with openall. If the CAL exit shutter is open for any reason and light is on, close it:

    IDL> tlc_move_cal,/exit,/close

    If you foresee a long debugging period, or if there is a possibility that you will lose your connection with the system or the AOC, power down the MEMS and woofer. Do this ONLY if you have successfully zeroed all of the mirrors.

    IDL> openall, /cal
    IDL> zeroall
    IDL> tlc_move_power,['MEMS','WOOFER'],/off

    If you cannot get the openall or zeroall commands to execute because the AOC is busy, try issuing an Abort command (See AOC is stuck on a command and refuses to accept any new input).


    The only time when it is even remotely acceptable to power down the mirrors without zeroing first is in the case of an AOC code or system crash. You can check for a code crash by SSHing into the AOC and running the status command at the prompt.

    Refer to: Top-level troubleshooting and Troubleshooting the AOC for help in diagnosing the problem.

    If possible, attempt to get a screenshot of any weird behavior on dispraw, or copy and save any errors you get in the IDL session and logs. Most importantly, note the exact time of the error so that it can be tracked down in all available logs.

    In many cases ult_sysalign will detect problems and stop execution. You will be stopped in the program’s scope and can attempt to continue (after diagnosing and debugging the error) by issuing the IDL directive .continue.

  7. Assuming ult_sysalign finished normally, and you requested a coronagraphic mode, you are now ready to take an IFS exposure. This is done with IDL program tlc_observe. Make sure that all loops are closed and healthy, and then close down the AO SF and open the CAL exit shutter:

    IDL> tlc_command_sf,2.8,/def    ;;2.8 is the nominal SF size and /def sends you to the default position
    IDL> tlc_move_cal,/exit,/open   ;;open the CAL exit shutter so light gets to the IFS
    IDL> tlc_observe, inttime=30    ;;integration times will vary with filter and source settings.

    If the IFS image is heavily saturated or otherwise misaligned (see figure below for reference), close the CAL shutter immediately before diagnosing the problem. Again, refer to the troubleshooting pages (Top-level troubleshooting and Troubleshooting the AOC) for help.


    Figure: Extracted IFS data cube showing a well-aligned coronagraph in H band. Note the symmetry in the PSF center and the symmetric shapes of the satellite spots.

  8. You are now ready for more advanced calibration tasks (Calibrations and Defaults) and focal plane wavefront controll (Speckle Nulling).

  9. When you have finished using GPI via gpilib run:

Footnotes to Quick Start Guide


GPI has a variety of hardware and software interlocks to monitor that the instrument is in a safe state to operate. These include checks for e.g. cabinet doors open, temperature warnings, whether the IFS is cold and has had its low-level initialization after coolind down, and other such low level stuff.

If any one is set, there is a big red warning on the main gpGui window, so it should be relatively obvious if something has interlocked.

Push the ‘Interlocks’ button at the right side of the main gpGui window to see the status of each interlock.

Simulating Mechanisms

Mechanisms can be simulated to prevent accidental motions, or to keep the software happy when something is not available. For instance there are some mechanisms which we do not expect to move routinely, or when the IFS is warming up the mechanisms are set to sim to prevent moving them outside of the operating temperature range.

To check if anything is simulated: look in the simulate column, just right of the state column in the main gui. This will be blank if normal, but will have the word “SIM” in red if anything is simulated. Open that subassembly to see which specific mechanism is simulated; in the subassembly GUIs there is likewise a Sim column next to the State for each mechanism, which displasy an asterisk if in simulated mode.

Note that there are 2 distinct levels of simulation:

  • MCD sim, which is lower level and only configurable via text config files
  • software sim mode, which can be adjusted in the GUIs.

Supercontinuum source: One noteworthy case is that the SC source in the ASU is set to sim mode if the laser is powered off at the power bar. (This is since when the laser is off there is no status information which leads to spamming the logs with warnings.) However normally the laser is turned to zero power but not actually off, so this sim mode case doesn’t occur that much. In any case, this is the software sim mode and the script automatically handle toggling it as needed.