System Alignment

The procedure gpilib/ultimate/ult_sysalign.pro is intended to be the primary method for system alignment via IDL. It attempts to use as many TLC and IS commands as possible (mirroring much of the GUIDE and ALIGN & CALIB commands from the IS) but is more flexible, and includes functionality not implemented (so far) in the IS.

ult_sysalign

ult_sysalign takes the following optional inputs:

Keyword Description
/guide User will be guided through the alignment with a series of questions. If this keyword is not set, the system assumes you know what you are doing and goes by the flags set (otherwise, flags are overwritten).
source ‘ASU’ or ‘TELSIM’. If unset, will try to automatically detect based on current laser/shutter settings
att Attenuation level (defaults to 25.5 dB)
asu_pos If set, overrides default ASU position with input value (see tlc_move_source for input format)
/lightonly Return after setting up source
aomag AO I magnitude for IS configuration (defaults to 4.0)
calmag CAL H magnitude for IS configuration (defaults to 0.0)
obsmode Observation mode. See tlc_obsmode for possible settings, or set to ‘None’ to stop at the CAL (defaults to H_coron)
zenith GPI’s zenith angle in degrees (defaults to 90). See tlc_set_zenith
ttlqg LQG case number (-1 for integral controller, defaults to 21) NOTE: Currently defaulting to integral controller. See ult_make_lqg
observer Observer name to pass to start_us_up and set_my_idl_mode
/nodarks Do not take new AO WFS darks (not recommended for fresh alignments)
/newflats Take new DM flats (not necessary unless you’ll need to flatten the AO mirrors manually)
/noaligncheck Skip apodizer & lyot alignment checks
/nosf Skip checking the SF alignment
/nocent Do not realign AO WFS to MEMS (will use previous best centering). Not recommended for fresh alignments
/nolqgset Do not set the LQG mode
/noquestions Don’t query user about turning on components or running start_us_up - just do it.
/usecalsphereintelsim Assume that the TELSIM is being fed by the CAL sphere.

The procedure executes the following. For more information on each step, see the Annotated Guide page:

  • Sets up the light source. Turns on the SC powerbar (if needed), takes the Source Assembly out of SIM (if needed), and sends an init and datum. Waits for laser to power on. Sets up ASU or TELSIM, turns on power and sets attenuation to the desired value.
  • If any of the AO controls are powered down, turns on their powerbars.
  • If common block values are not defined, runs start_us_up, /mode_ifs.
  • Run Instrument Sequencer AO Config command. This is the same command that Seqexec uses to set up for a star, based on its expected magnitude. Sets frame rates, adjust optimizer, adjust spatial filter. In this case it will be configured for the 4th-mag-equivalent ASU.
  • Closes the Spatial Filter to 4.0 mm.
  • Datums AO PnCs and inputfold, and finds new AO Tip/Tilt flat with ult_task_point.
  • Applies prior best-found centering to AO PnCs. This uses saved values from the previous time ult_sysalign was executed (saved at an IDL level, not in the TLC or AOC code).
  • Puts in CLEARGP position on Apodizer wheel, and checks light levels on the AO WFS and LOWFS.
  • Closes CAL loop and AO TT and Woofer loops, puts AO PnCs in TRACK and applies CAL corrections. Drags the star to the center of the CAL: Waits until CAL Tip/Tilt residuals are below 5 mas RSS as measured on LOWFS. Saves new AO PnC pointing.
  • Gets current flattening Tip/Tilt via ult_get_cl_tt and stores.
  • Opens all loops and flattens AO components.
  • (If using TELSIM, puts inputfold in track and applies pupil offsets.)
  • Checks and fixes the MEMS-to-AOWFS alignment. By default, it does this using an IDL code, which provides a wider capture range than the IS version. The IDL version is thus more robust but less precise than the IS code. It is also slower. However, if you are running using /guide then it asks you which of these you would prefer to use.
  • If requested, checks the SF centering.
  • If requested, gets new AO WFS darks with ult_measure_darks.
  • If requested, gets new DM flats with ult_measure_dm_flats.
  • If obsmode is ‘None’, moves FPM to SCIENCE and returns.
  • Otherwise, sets the selected obsmode to the instrument sequencer.
  • Puts CAL IFS PnCs in track (with Lyot offsets applied).
  • If requested, checks alignment of Lyot and Apodizer.
  • If FPM is not OPEN or SCIENCE, runs alignfpm_and_centerpin and returns with loops closed; otherwise, returns with loops open.

At the end of this process (if run with a coronagraph obsmode) all loops will be closed, AO and CAL PnCs will be tracking (inputfold will be tracking if using TELSIM), and CAL bias will be set to align to FPM.

Manually Steering System Components

While GPI operation is inteded to be automatic, there are occassionally instances where you may wish to manually steer certain system components. These include:

  • moving the beam on the FPM to better hit the pinhole (in cases where it is off), or
  • moving the PnC mirrors to change the wavefront on the AO WFS, or the location of the final science image on the array (useful for getting widely separated objects).

Moving the Beam on the FPM in Closed Loop

When operating fully in closed loop (all AO & CAL loops closed and all components tracking), the beam location on the IFS is controlled via the CAL Tip/Tilt bias values. These are displayed on gpidiagram and can be queried by running:

IDL> calttbias = tlc_get_cal_tt_bias()

which returns a 2x1 array with the tilt and tip biases, respectively, in mas. To set a new set of bias values, use:

IDL> tlc_set_cal_tt_bias,calttbias

where calttbias is again a 2x1 array of tilt, tip in mas. You can use these functions together to make relative changes to the biases:

IDL> calttbias = tlc_get_cal_tt_bias()
IDL> tlc_set_cal_tt_bias,calttbias+[tilt_offset_in_mas, tip_offset_in_mas]

Note

This procedure will only produce a change if all loops are closed and the system is tracking. The gain on this loop is quite low, so it may take a while for it to converge to a new position.

Warning

If DAR offsets are being applied, and you are not in H band, the CAL bias values are not the sensed Tilt/Tip values that the CAL will be driven to. In this case, it is safest to use relative offsets, as described above.

Moving the Beam on the WFS

Warning

This can be done in closed loop, but may cause loss of light and should only be done if you know exactly what you are doing. Moving the AO PnCs takes them out of track. You must put them back in track if you want CAL corrections and/or open loop models to be applied again after your move.

To move the beam on the AO WFS in pointing, centering, and/or focus, use:

IDL> tlc_command_pnc_pc,/relative,[tip_offset,tilt_offset,xcent_offset,ycent_offset,focus_offset]

where the tip and tilt offsets are in mas and the centering and focus offsets are in mm.

Moving the Image Center on the IFS

Note

This can be done in closed loop with no safety concerns. However, moving the CAL-IFS PnCs takes them out of track. You must put them back in track if you want open loop models to be applied after your move.

You can change the beam pointing, centering, and focus on the IFS with the CAL-IFS PnC mirrors. As with the AO PnCs, we can make relative changes by running:

IDL> tlc_command_cal_pnc_pc,/relative,[tip_offset,tilt_offset,xcent_offset,ycent_offset,focus_offset]

where the tip and tilt offsets are in mas and the centering and focus offsets are in mm.

In order to move the spot location in the final image, it is necessary only to make pointing changes:

IDL> tlc_command_cal_pnc_pc,/relative,[x,y,0,0,0]

where x and y are in mas and their relative orientations are given in the figure below:

_images/califs_pnc_orientation.png

Figure: Schematic of spot motion in the focal plane due to CAL-IFS PnC pointing changes.

The pixel scale in IFS images is 14.14 mas/pixel.

Alignment Functions

Summary

Function  
apply_active_state  
cal_howfs_peek  
cal_mach_zehnder_mode  
get_active_state  
svncheckout (gpi_checkout.pro)  
envvarcheckout (gpi_checkout.pro)  
gpi_checkout (gpi_checkout.pro)  
load_telem  
ult_ao_status  
ult_check_etf  
ult_check_focus_mode  
ult_check_light_level  
ult_check_ref_mode  
ult_check_tt_mode  
ult_check_twt_infl_cal  
ult_cl_focus  
ult_get_centering_acts_lenslets  
ult_get_centering_pupil_lenslets  
ult_get_cents  
ult_get_cl_tt  
ult_get_headervals  
ult_get_intensity  
ult_get_phase  
ult_get_phase_from_flat  
ult_get_pointing  
ult_get_pointing_lowlight  
ult_psds_save (ult_get_psds.pro)  
ult_psds_load (ult_get_psds.pro)  
ult_psds_plot_tt (ult_get_psds.pro)  
ult_psds_plot_act (ult_get_psds.pro)  
ult_psds_plot_fmodes (ult_get_psds.pro)  
ult_get_psds (ult_get_psds.pro)  
ult_get_rotation  
ult_get_rotfoc  
ult_get_telem_path  
ult_locate_actuators  
ult_log  
ult_make_cal_filter  
ult_make_cleanup_modes  
ult_make_focus_shape  
ult_make_ftr_filter  
retrieve_lqg_parameters (ult_make_lqg.pro)  
cofz_from_lqg_parameters1 (ult_make_lqg.pro)  
cofz_from_lqg_parameters (ult_make_lqg.pro)  
process_lqg_parameters1 (ult_make_lqg.pro)  
process_lqg_parameters (ult_make_lqg.pro)  
apply_lqg (ult_make_lqg.pro)  
glqgp_lookup_vals (ult_make_lqg.pro)  
glqgp_lookup_case (ult_make_lqg.pro)  
ult_make_lqg (ult_make_lqg.pro)  
ult_make_mta  
ult_make_phs_vlt  
ult_make_rotfoc_vectors  
ult_make_subapmask  
ult_measure_darks  
ult_measure_dm_flats  
ult_measure_etf  
ult_measure_fmode_intensity  
ult_measure_parallax  
ult_measure_refs  
ult_offset_refs_with_rotation  
ult_save_dm_flats  
ult_set_dark_corner  
ult_set_focus_mode  
ult_set_tt_mode  
ult_setup_onsky  
ult_skydarks  
ult_status  
ult_subtask_sf_raster  
ult_sysalign  
ult_take_ao_darks  
ult_task_align_apod  
ult_task_align_lyot  
ult_task_breakdown_pinhole  
ult_task_center_acts  
ult_task_center_acts_is  
ult_task_center_pupil  
ult_task_make_pinhole  
ult_task_point  
ult_task_point_asu  
ult_task_point_pnc  
ult_task_sf_center  
ls_modhdr (ult_telem.pro)  
ult_telem_save (ult_telem.pro)  
ult_telem (ult_telem.pro)  
ult_ttlqg_final_set  
ult_tweak_mta  
ult_twt_leak_map  
ult_wferms  

Functions

apply_active_state

pro apply_active_state, cur_active_state

NAME:
      apply_active_state
PURPOSE:
      Apply the state (stored in structure cur_active_state) to
      active elements in the system.

EXPLANATION:
      see above.

Calling SEQUENCE:
      apply_active_state, cur_active_state

INPUT/OUTPUT:
     cur_active_state - Active state structure (currently just
                        woofer and tweeter).

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_command_set_tweeter
     rtc_command_set_woofer

NOTES:


REVISION HISTORY
      written 2011-12-? by LAP

cal_howfs_peek

pro cal_howfs_peek, min=min, max=max, ref_arm=ref_arm, sci_arm=sci_arm, inter=inter, all=all

NAME:
      cal_howfs_peek

PURPOSE:
      Examine light going into the CAL and display.

EXPLANATION:
               Can also specify which modes to take images.
               Modes are reference arm only, science arm only, and interferometric mode.

Calling SEQUENCE:
      cal_howfs_peek, /all

INPUT/OUTPUT:
               min = minimum value for display
               max = maximum value for display
               ref_arm - take HOWFS image of reference arm (passes back image)
               sci_arm - take HOWFS image of science arm (passes back image)
               inter - take HOWFS image in interference mode (both arms open) - passes back image
               all - take 3 images, one per mode


OPTIONAL OUTPUT:


EXAMPLES:
               cal_howfs_peek, sci_arm=sci_arm, inter=inter

REVISION HISTORY
      Written, 11/12/2015 by PI

cal_mach_zehnder_mode

pro cal_mach_zehnder_mode

No header information available.

get_active_state

function get_active_state

NAME:
      get_active_state
PURPOSE:
      Get the state (stored as a structure) of
      active elements in the system.

EXPLANATION:
      see above.

Calling SEQUENCE:
      res = get_active_state()

INPUT/OUTPUT:
     res - State of current TT, woofer, tweeter,

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata
     new_extract_tt_Types_from_telemetry

NOTES:
    Update with TLC stuff too?

REVISION HISTORY
      written 2011-12-? by LAP

svncheckout (gpi_checkout.pro)

pro svncheckout, lun, fname, pname, dname

envvarcheckout (gpi_checkout.pro)

pro envvarcheckout, lun, varname

gpi_checkout (gpi_checkout.pro)

pro gpi_checkout, debug=debug, nodatestamp=nodatestamp

NAME:
     gpi_checkout

PURPOSE:
     Wrapper around ult_sysalign to verify GPI system and operating
     environment end to end.  An output log is automatically
     generated in the home directory.

CALLING SEQUENCE:
     gpi_checkout [,/debug,/nodatestamp]

INPUT/OUTPUT:
     /debug - Do not run ult_sysalign (only checks paths and SVN status)
     /nodatesatmp - Do not datestamp output log

OPTIONAL OUTPUT:
      None.

EXAMPLES:


DEPENDENCIES:
       ult_sysalign
      tlc_observe

NOTES:

REVISION HISTORY
     Written 08.26.14 - ds

load_telem

pro load_telem, tag, show37=show37

No header information available.

ult_ao_status

pro ult_ao_status, nframes=nframes, verbose=verbose

 NAME:
       ult_ao_status

 PURPOSE:
       Function to quickly spit out the average RMS WFE (actuator by
       actuator) as well as the TT vibration info. Also prints WFS flux.

 EXPLANATION:
       Uses the recovered 'phase' variable (which is the FT of the
       AOC-dumped phase) - should be equal to sum of woofer and
       tweeter phase
       Plots TT PSDs and power in 60Hz+multiples

 Calling SEQUENCE:
       wfe_tt_status

 INPUT/OUTPUT:
       nframe - Number of frames to dump (defaults to
                 current frame rate; ie: 1 second)
       /verbose - display extra summary info

 EXAMPLES:
      wfe_tt_status
      wfe_tt_status, nframes=2000, /verb

 DEPENDENCIES:
      zernikefit
      rtc_retrive_dumpdata
      get_current_tt

 NOTES:
      based on ult_wferms & tt_log


ommon gpi_globals

ult_check_etf

pro ult_check_etf, tag, per_len=pflag, ttdelay=ttdelayflag

No header information available.

ult_check_focus_mode

pro ult_check_focus_mode, log=logname

NAME:
      ult_check_focus_mode

PURPOSE:
      Print out in nice, helpful fashion, the current TT controller method.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_check_focus_mode, [lun=lun]

INPUT/OUTPUT:
      lun=lun : pass in a logic unit to make it write to a file
      instead of stdout.
      no outputs

      prints out helpful info to stdout about the TT controller parameters

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_make_lqg.pro to get the details with glqgp_lookup_case


NOTES:



REVISION HISTORY
    Written in 2012. Added to final SVN in ultimate by LAP on 11 Feb 2013.
    ****** NEW March 22, 2014!

ult_check_light_level

pro ult_check_light_level, analyze=aflag, stop=stopflag, log=logname

NAME:
     ult_check_light_level

PURPOSE:
     Return information on current illumination as seen by AO WFS.

CALLING SEQUENCE:
     ult_check_light_level,[analyze=aflag,/stop,log=logname]

INPUT/OUTPUT:
     analyze - Set to when_string() to analyze existing files
     /stop - Stop before returning
     log - Set to filename to log output.

OPTIONAL OUTPUT:
     None.

EXAMPLES:

DEPENDENCIES:

NOTES:

REVISION HISTORY
     Written by LAP

ult_check_ref_mode

pro ult_check_ref_mode, log=logname

NAME:
      ult_check_ref_mode

PURPOSE:
      Print out in nice, helpful fashion, the current references

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_check_ref_mode, [lun=lun]

INPUT/OUTPUT:
      lun=lun : pass in a logic unit to make it write to a file
      instead of stdout.
      no outputs

      prints out helpful info to stdout about the TT controller parameters

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     get_curr_refcents


NOTES:
    THis is a wrapper for Lisa's convenience of config/get_curr_refcents


REVISION HISTORY
    New, 20-Feb-2013. BY LAP

ult_check_tt_mode

pro ult_check_tt_mode, log=logname

NAME:
      ult_check_tt_mode

PURPOSE:
      Print out in nice, helpful fashion, the current TT controller method.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_check_tt_mode, [lun=lun]

INPUT/OUTPUT:
      lun=lun : pass in a logic unit to make it write to a file
      instead of stdout.
      no outputs

      prints out helpful info to stdout about the TT controller parameters

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_make_lqg.pro to get the details with glqgp_lookup_case


NOTES:



REVISION HISTORY
    Written in 2012. Added to final SVN in ultimate by LAP on 11 Feb 2013.

ult_check_twt_infl_cal

pro ult_check_twt_infl_cal, sfsize, analyze=aflag, ref=refflag, smallerpupil=spflag, inflprecomp=ipflag, allmodes=allflag, stop=stopflag

No header information available.

ult_cl_focus

pro ult_cl_focus, foc_mic, pv=pv, refcent_name=refcent_name

NAME:
      ult_cl_focus

PURPOSE:
      Apply requested amount of focus in closed loop.

EXPLANATION:
      Generate a pure focus term and add it is a phase offset to
      closed loop operation via offset reference centroids.

Calling SEQUENCE:
      ult_cl_focus,foc_mic[,/pv,refcent_name=refcent_name]

INPUT/OUTPUT:
      foc_mic - Amount of focus to apply in microns
      /pv - Given value of foc_mic is peak to value (default is rms)

OPTIONAL OUTPUT:
      refcent_name - On return will contain the filename of the
                     dumped references file

EXAMPLES:

DEPENDENCIES:
     offset_wfscen_phase
     zernike


NOTES:
    Currently using Don's zernike generator (maybe can switch to
    Lisa's)

REVISION HISTORY
      Written by bmac at some point
      Folded into gpilib 4/5/2015 ds

ult_get_centering_acts_lenslets

function ult_get_centering_acts_lenslets, dontbothertosavestate=dflag, stop=stopflag, useaoc=useaoc, option=option

NAME:
      ult_get_centering_acts_lenslets

PURPOSE:
      Measure the centering offset between tweeter actuators and WFS
      lenslets.

EXPLANATION:
      Compare an input poke pattern to the measured phase and return
      the centering offset.

Calling SEQUENCE:
      res = ult_get_centering_acts_lenslets([/dontbothertosave,/stop,/useaoc,option=option])

INPUT/OUTPUT:
      /dontbothertosave - If set, does not preserve the current
                          state (i.e., some components may be moved
                          at the end of the measurements).
     /stop - Stop before returning
     /useaoc - Use the version of this code built into the AOC
     option - Change the poke pattern used.  Default is 1
              1 - Ring of 12 pokes 16 pix from center
              2 - Four pokes in square 15 pix about center
              3 - Four gaussians in a square 12 pix about center
              4 - Four pokes in diamond pattern 10 pix about center
              5 - Ring of pokes 16 pix from center
              6 - Ring of Gaussians 17 pix from center

     res - Centering offset in fractions of a subaperture.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     get_active_state
     apply_active_state
     tlc_find_binary
     rtc_issue_command
     ult_get_phase_from_flat
     run_readwrite_query
     per_corr

NOTES:
    This functionality is now handled by TLC calls directly to the
    AOC function.  This routine is retained as an independent check
    and to quickly test out alternate poke shapes.

REVISION HISTORY
      written 2011-11-23 by LAP
      Added calls to AOC function - ds

ult_get_centering_pupil_lenslets

function ult_get_centering_pupil_lenslets

NAME:
      ult_get_centering_pupil_lenslets

PURPOSE:
      Measure the centering offset between the telescope pupil and WFS
      lenslets.

EXPLANATION:
      Perform and autocorrelation on the AO WFS intensity pattern
      and return the offset from center.

Calling SEQUENCE:
      res = ult_get_centering_pupil_lenslets()

INPUT/OUTPUT:
     res - Centering offset in fractions of a subaperture.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata
     calculate_intensities
     per_corr

NOTES:
    This functionality is now handled by TLC calls directly to the
    AOC function.  This routine is retained as an independent
    check.  This measurement only makes sense when you have an input
    pupil (i.e., not when running with the ASU).

REVISION HISTORY
      written 2011-11-23 by LAP

ult_get_cents

function ult_get_cents

NAME:
      ult_get_cents

PURPOSE:
      simple wrapper to get centroids easily

EXPLANATION:
      see above.

Calling SEQUENCE:
      c = ult_get_cents()

INPUT/OUTPUT:
      return a centroi 96 x 48 file (mas)

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:

REVISION HISTORY
    added 12-07-2011 by LAP

ult_get_cl_tt

function ult_get_cl_tt

NAME:
     ult_get_cl_tt

PURPOSE:
     Get the TT commands presently on the Stage. **** WARNING****
     this does not get you the total TT on the Stage + WFr
     Surface. THis will, hoever, give you the sSTage, which works
     when you are correcting a static error.

CALLING SEQUENCE:
     res = ult_get_cl_tt()

INPUT/OUTPUT:
     res: the 2-element vector of TTT for the stage, in mas



OPTIONAL OUTPUT:
     None.

EXAMPLES:

DEPENDENCIES:


NOTES:
     Used to be rtc_get_cl_tt.pro

REVISION HISTORY
     Written by Lisa Poyneer at some point.

ult_get_headervals

function ult_get_headervals, whentag=whentag

NAME:
      ult_get_headervals

PURPOSE:
      Grab various header values from the GMB and epics channels

EXPLANATION:
      Recreate a large chunk of the IFS headers manually

CALLING SEQUENCE:
      res = ult_get_headervals()

INPUT/OUTPUT:
      res - FITS header

OPTIONAL OUTPUT:
      None

EXAMPLE:


DEPENDENCIES:
       Assumes access to executables in $TLC_ROOT and accessible
       connection to server tlc.  Also needs caget to be installed
       for epics channel queries
      tlc_find_binary.pro
      run_readwrite_query

NOTES:


REVISION HISTORY
      Written 09.09.2014 - ds
      05.29.2015 - ds - Added airmass and DIMM/MASS/WIND keywords

ult_get_intensity

function ult_get_intensity

NAME:
      ult_get_intensity

PURPOSE:
      Return the intensity profile as measured by the AO WFS.

EXPLANATION:
      Wrapper for rtc_retrieve_dumpdata

Calling SEQUENCE:
      res = ult_get_intensity()

INPUT/OUTPUT:
     res - 48x48 array of WFS values.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata

NOTES:

REVISION HISTORY
      written 2011-12-07 by LAP

ult_get_phase

function ult_get_phase

NAME:
      ult_get_phase

PURPOSE:
      Return the phase as measured by the AO WFS.

EXPLANATION:
      Wrapper for rtc_retrieve_dumpdata

Calling SEQUENCE:
      res = ult_get_phase()

INPUT/OUTPUT:
     res - Array of phase values

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata

NOTES:

REVISION HISTORY
      written 2011-12-07 by LAP

ult_get_phase_from_flat

function ult_get_phase_from_flat, sig, dontbothertosavestate=dflag

NAME:
      ult_get_phase_from_flat

PURPOSE:
      Return the phase as measured by the AO WFS for a given input
      shape relative to the phase of the currently stored DM flat.

EXPLANATION:
      Puts shape sig on the MEMS, measures the phase, flattens MEMS,
      measures the phase, and then subtracts the two.

Calling SEQUENCE:
      res = ult_get_phase_from_flat(sig,[/dontbothertosavestate])

INPUT/OUTPUT:
     /dontbothertosavestate - By default, mirrors are returned to
                              the state they had before this
                              function was called, unless this flag
                              is set.
     res - Array of delta phase values

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata
     get_active_state
     rtc_command_set_tweeter

NOTES:

REVISION HISTORY
      written 2011-12-07 by LAP

ult_get_pointing

function ult_get_pointing

NAME:
      ult_get_pointing

PURPOSE:
      Returns the tip/tilt (in mas) as measured by the AO WFS.

EXPLANATION:
      Wrapper for rtc_retrieve_dumpdata

Calling SEQUENCE:
      res = ult_get_pointing()

INPUT/OUTPUT:
     res - [Tip,Tilt]  (mas)

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata
     new_extract_tt_types_from_telemetry

NOTES:
     These values are also available via the GMB in the AOC display
     vars.

REVISION HISTORY
      written 2011-11-23 by LAP

ult_get_pointing_lowlight

function ult_get_pointing_lowlight

NAME:
      ult_get_pointing

PURPOSE:
      Returns the tip/tilt (in mas) as measured by the AO WFS.

EXPLANATION:
      Wrapper for rtc_retrieve_dumpdata

Calling SEQUENCE:
      res = ult_get_pointing()

INPUT/OUTPUT:
     res - [Tip,Tilt]  (mas)

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata
     new_extract_tt_types_from_telemetry

NOTES:
     These values are also available via the GMB in the AOC display
     vars.

REVISION HISTORY
      written 2011-11-23 by LAP

ult_psds_save (ult_get_psds.pro)

pro ult_psds_save, res

ult_psds_load (ult_get_psds.pro)

function ult_psds_load, tag

ult_psds_plot_tt (ult_get_psds.pro)

pro ult_psds_plot_tt, res, linear=linflag, yrange=yranflag, integ=intflag, vib_vals=vib_vals

ult_psds_plot_act (ult_get_psds.pro)

pro ult_psds_plot_act, res

ult_psds_plot_fmodes (ult_get_psds.pro)

pro ult_psds_plot_fmodes, res

ult_get_psds (ult_get_psds.pro)

function ult_get_psds, second=secflag, ttonly=ttflag, tag=tag

NAME:
      ult_get_psds

PURPOSE:


EXPLANATION:
      see above.

Calling SEQUENCE:
      res = ult_get_psds([sec=num])

INPUT/OUTPUT:
      sec=num is the number of seconds over which to take data. This
      enforces a minimum of 5.5 seconds (one large data dump). Any
      input under 5.5 will result in 5.5 seconds. No upper limit.

      This returns a structure which has the raw TT and residual
      phase data, as well as PSDs of these. This data is also saved
      to disk in private/psds/ with the tag mathcing res.tag so you
      can load it in later.
        OPTIONAL OUTPUT:
      tag - Time stamps of data set

EXAMPLE:


DEPENDENCIES:




NOTES:
    Once you do this, you'll want to display htings nicely. Ala
    IDL> ult_psds_plot_tt, res, /lin ;;;; display TT psds xlin
    IDL> ult_psds_plot_act, res ;;; display a few actuator psds


REVISION HISTORY
    written in 20XX by LAP.

ult_get_rotation

function ult_get_rotation, long=lflag, show=showflag, save=saveflag

NAME:
     ult_get_rotation

PURPOSE:
      Measure the effective rotation seen by the WFS.

EXPLANATION:
      The WFS itself has a known non-negligible rotation between the
      spot grid formed by the lenslets and the CCD pixels. If the
      gain per subap changes (due to spot size changes, a change in
      backgornud light or a drift in the detector), this rotation
      will not be fuly measured, leading to a wind up in close loop
      and potenitally instability. See gpilib online doc for more details.

Calling SEQUENCE:
      rot = ult_get_rotation()

INPUT/OUTPUT:
      /long to take a longer (5 second) measurement
      /show to display the centroids and the rotation component
      /save to save the measurement

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:

REVISION HISTORY
    written in 2012 by LAP.

ult_get_rotfoc

function ult_get_rotfoc, realunits=rflag

NAME:
      ult_get_rotfot

PURPOSE:
      Returns the rotation and focus coefficients from telemetry.
      If you use the real units flag, will return data in real units.

EXPLANATION:
      Wrapper for rtc_retrieve_dumpdata

Calling SEQUENCE:
      res = ult_get_rotfoc()

INPUT/OUTPUT:
     res - [rot, foc] (coefficients)

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     rtc_retrieve_dumpdata
     new_extract_tt_types_from_telemetry

NOTES:
     These values are also available via the GMB in the AOC display
     vars.

REVISION HISTORY
      written 2011-11-23 by LAP

ult_get_telem_path

function ult_get_telem_path, tag, old=oflag, reduced=reducedflag, short=shortflag, query=queryflag

NAME:
      ult_get_telem_path

PURPOSE:
      find where the data are stored! Old and new formats (reorg Dec 2015)

EXPLANATION:


Calling SEQUENCE:
      path = ult_get_telem_path('_When_2015.12.10_3.3.3')

INPUT/OUTPUT:
     path - a string which is the full path to that AO telem set,
            excluding the suffix. E.g.
     path = '/Users/poyneer1/Onsky/aotelem/Raw/20151210/ugp_When_2015.12.10_3.3.3_'

OPTIONAL OUTPUT:
      None.

EXAMPLE:
     To get the full path, e.g. in load_telem
       print, ult_get_telem_path('_When_2015.12.10_3.3.3')
   /Users/poyneer1/Onsky/aotelem/Raw/20151210/ugp_When_2015.12.10_3.3.3_

     To get the path for *reduced* data
       print, ult_get_telem_path('_When_2015.12.10_3.3.3', /reduced)
   /Users/poyneer1/Onsky/aotelem/Reduced/20151210/aored_When_2015.12.10_3.3.3_

   * if you are still on the old file storage system use /old
     print, ult_get_telem_path('_When_2015.12.10_3.3.3', /old)
  /Users/poyneer1/Onsky/gpilib/private/psds/ugp_When_2015.12.10_3.3.3_


     To get just the name with no leading directory:
       print, ult_get_telem_path('_When_2015.12.10_3.3.3',/short)
   ugp_When_2015.12.10_3.3.3_

       print, ult_get_telem_path('_When_2015.12.10_3.3.3',/reduced, /short)
   aored_When_2015.12.10_3.3.3_

     To get a path that you will use to save data
       path = ult_get_telem_path('_When_2015.12.10_3.3.3', /query)
       ---> Directory /Users/poyneer1/Onsky/aotelem/Raw/20151210/ does not exist. Creating it...

DEPENDENCIES:

NOTES:
   Use the query flag when you want a path to *save* data into. It
   will check to see if the dated dirtectory,
   e.g. aotelem/Raw/20151210 exists. If it does not yet exist, it
   will create it.


REVISION HISTORY
      written 2011-12-07 by LAP

ult_locate_actuators

pro ult_locate_actuators, tweet=tflag, woof=wflag, stop=stopflag, analyze=aflag

NAME:
      ult_locate_actuators

PURPOSE:
      Pokes actuators on the

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_locate_actuators, [/tweet, /woof, /stop, analyze=tag]

INPUT/OUTPUT:
      writes files which store actuator locations to disk.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     internal/save_actuator_locations

NOTES:


REVISION HISTORY
    written in 2011 by LAP.

ult_log

pro ult_log, tag, message

NAME:
      ult_log

PURPOSE:
      Write log file.

EXPLANATION:
      See above.

Calling SEQUENCE:
      ult_log,tag,message

INPUT/OUTPUT:
     tag - filename specifier
     message - String to log

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:
     Logs are written to gpi_idl_private_datapath (in common
     gpi_globals).

REVISION HISTORY
      written 2011-12-07 by LAP

ult_make_cal_filter

pro ult_make_cal_filter, modhud=modflag, lowfs=loflag

NAME:
      ult_make_cal_filter

PURPOSE:
      Save CAL reconstruction filter.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_make_cal_filter,[/modhud,/lowfs]

INPUT/OUTPUT:
      /modhud - Generate FTR filter (mod-hud geometry).  If not set,
                simply copies the tweeter reconstruction filter.
      /lowfs -  Restrict the CAL filter to pass only the modes that
                the LOWFS can see.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     fill_out_to_hermitian
     complexmp

NOTES:
    This should be used only very rarely!
    The filter is only used once you run a readconfig.

REVISION HISTORY
    written 06-28-2012 LAP
    typo fixed by bmac 01-15-2013

ult_make_cleanup_modes

pro ult_make_cleanup_modes, slaveadjustment=saflag, nofocus=nofflag, notriangle=notflag

NAME:
      ult_make_cleanup_modes

PURPOSE:
      Produce the parameter files specified by TWT_CLEANUP and
      WFR_CLEANUP in parms.txt.

EXPLANATION:
      Given the current MTA (wfr-Twt split), generate the modes on
      the Wfr that are not controlled. Also generate the modes on
      the Twt that are not controlled. See gpilib online doc for
      much more detail.

Calling SEQUENCE:
      ult_make_cleanup_modes [, /slaveadjustment]

INPUT/OUTPUT:
      no inputs
      no outputs
      changes two files on disk - the cleanup modes.


OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:



NOTES:



REVISION HISTORY
    Written in 2011. Added final version to Ultimate by LAP on 11
    Feb 2013.
   Discovered March 2013 that we *must* remove TT from Wfr cleanup
   modes. This is now the default mode of operation.

ult_make_focus_shape

function ult_make_focus_shape, triangle=tflag

NAME:
      ult_make_focus_shape

PURPOSE:
      This generates the 9x9 Wfr commands (phase) that produce pure
      focus, as is calculated by one unit of the vectors saved for
      the Focus projection!

EXPLANATION:
      Use this to generate the vector for the FOcus control.

Calling SEQUENCE:
      IDL> wfr_comm = ult_make_focus_shape()

INPUT/OUTPUT:
     INputs: none

      Outputs: returns the 9 x 9 wfr command that makes pure focus

OPTIONAL OUTPUT:
      None

EXAMPLE:

DEPENDENCIES:
     only other functions/procedures in this file

NOTES:


REVISION HISTORY
     Written March 10, 2014 by LAP.
initial version uses a projection on Wfr actuators as with the
offloading matrix.

ult_make_ftr_filter

pro ult_make_ftr_filter, modhud=modflag

NAME:
      ult_make_ftr_filter

PURPOSE:
      Save tweeter reconstruction filter.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_make_ftr_filter,[/modhud]

INPUT/OUTPUT:
      /modhud - Generate FTR filter (mod-hud geometry).  If not set,
                simply copies the tweeter reconstruction filter
                currently in the AOC.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     fill_out_to_hermitian
     complexmp
     store_value

NOTES:
    This should be used only very rarely!
    The filter is only used once you restart the AOC code.

REVISION HISTORY
    written 06-28-2012 LAP

retrieve_lqg_parameters (ult_make_lqg.pro)

function retrieve_lqg_parameters, default=dflag, getnow=gflag, ch1, ch2, ch3, stop=stopflag, no_ncp_vib1=nncp1, no_ncp_vib2=nncp2, no_ncp_vib3=nncp3, no_cp_vib1=ncp1, no_cp_vib2=ncp2, no_cp_vib3=ncp3, swap_cp_vib1=scp1, swap_cp_vib2=scp2, swap_cp_vib3=scp3, flip_cp_vib1=fcp1, flip_cp_vib2=fcp2, flip_cp_vib3=fcp3, focus=focusflag

NAME:
      retrieve_lqg_parameters

PURPOSE:
      LQG helper: get the three keyword values from parms.
      ** in you give it three numbers as ch1, ch2, ch3, it will
      return the index for the LQG case that those specify.
      ** if you use the /getnow flag, it will parse parms.txt and
      return the index of the case that is being used NOW. Will
      also return the values of the three keywords into ch1, ch2,
      ch3, overwriting whatever you had in those variables.

EXPLANATION:
      LQG: to tell what mode you are running!

Calling SEQUENCE:
      index = retrieve_lqg_parameters(ch1, ch2, ch3, [/stop,
      /default, /getnow]

INPUT/OUTPUT:
      ch1, ch2, ch3 are three input that give the values of the
      keyword. If you specify these and not /getnow, they are used
      as a lookup. If you specify /getnow, these will be overwritten
      with what is presently in parms.txt.

      /stop -    stop the code so you can inspect

      /default - the default case if 1,1,1 for each of the
                 selectors. Here for historial reasons and probably
                 rarely used

      /getnow -  Parse parms and deal with the case in use now. Most
                common method of usage is this one.

OPTIONAL OUTPUT:
      None

EXAMPLE:
     From finaltests/test_cl_psd5_ttlqg:
         lqg_parmvec = retrieve_lqg_parameters(/getnow)

DEPENDENCIES:
     only other functions/procedures in this file

NOTES:


REVISION HISTORY
     written in 2012. Added to SVN in final version 11 Feb 2013 by LAP

cofz_from_lqg_parameters1 (ult_make_lqg.pro)

function cofz_from_lqg_parameters1, mystr, zinv, stop=stopflag

NAME:
      cofz_from_lqg_parameters1

PURPOSE:
      LQG helper: returns the C(z) complex function for a given
      controller. Used when analyzing temporal PSDs to verify LQG
      impleentation and performance

EXPLANATION:
      LQG: This uses known equations to evaluate the controller
      transfer function C(z) from a state space model and LQG controller.

Calling SEQUENCE:
      cofz = cofz_from_lqg_parameters(lqg_structure, zinv [, /stop])

INPUT/OUTPUT:
      First input mystr is an lqg structure which contains the
      description of the LQG filter. (as generated by
      process_lqg_parameters, see code below).

      Second input zinv is a complex-valued vector which is the
      complex number z^{-1} sampled from -!pi to !pi.

      Returns a cmoplex-valued signal which is C(z)

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     only other functions/procedures in this file

NOTES:
    Uses the state equations of the filter (see gpilib documentation
    on line and corresponding papers, to directly calculate the
    transfer function.

 ************* uses correct Dmat, not weird dmat!!!!!!

REVISION HISTORY
    Written in 2012. Added to SVN in final version on 11 Feb 2013 by LAP
    Error discovered March 19, 2013. The IDL code was not correctly
    using the estimate command is the linear interpolation between
    the two estimates!. Have to change the
    functions the produce the state space matrices and calculate the
    C(z) transfer functions and apply the filter!!!!! - LAP

cofz_from_lqg_parameters (ult_make_lqg.pro)

function cofz_from_lqg_parameters, mystr, zinv, stop=stopflag

NAME:
      cofz_from_lqg_parameters

PURPOSE:
      LQG helper: returns the C(z) complex function for a given
      controller. Used when analyzing temporal PSDs to verify LQG
      impleentation and performance

EXPLANATION:
      LQG: This uses known equations to evaluate the controller
      transfer function C(z) from a state space model and LQG controller.

Calling SEQUENCE:
      cofz = cofz_from_lqg_parameters(lqg_structure, zinv [, /stop])

INPUT/OUTPUT:
      First input mystr is an lqg structure which contains the
      description of the LQG filter. (as generated by
      process_lqg_parameters, see code below).

      Second input zinv is a complex-valued vector which is the
      complex number z^{-1} sampled from -!pi to !pi.

      Returns a cmoplex-valued signal which is C(z)

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     only other functions/procedures in this file

NOTES:
    Uses the state equations of the filter (see gpilib documentation
    on line and corresponding papers, to directly calculate the
    transfer function.

REVISION HISTORY
    Written in 2012. Added to SVN in final version on 11 Feb 2013 by LAP
    Error discovered March 19, 2013. The IDL code was not correctly
    using the estimate command is the linear interpolation between
    the two estimates!. Have to change the
    functions the produce the state space matrices and calculate the
    C(z) transfer functions and apply the filter!!!!! - LAP

process_lqg_parameters1 (ult_make_lqg.pro)

function process_lqg_parameters1, v, delta, funky=funky

NAME:
      process_lqg_parametersq

PURPOSE:
      LQG helper: Given the vector of parameters stored on disk,
      generate a usable state space model for the system and the LQG
      controller.

EXPLANATION:
      LQG:

Calling SEQUENCE:
      lqg_parms = process_lqg_parametersq(v, delta)

INPUT/OUTPUT:
      input v is the lqg_parmvec produced by
      retrieve_lqg_parameters.pro See below for more detail. This is
      just a bunch of numbers which comprises one entry in the
      config file that the AOC reads in.

     input delta = total comp delay/frame time - 1 per paper

OPTIONAL OUTPUT:
      None.

EXAMPLE:
     lqg_parms = process_lqg_parametersq(lqg_parmvec, delta)

DEPENDENCIES:
     only other functions/procedures in this file

NOTES:

 get delta this way :
     delta = (retrieve_value('TT_DELAY_MICROSECS' + ...
     1000e-6))/(1./this_frame_rate) - 1


REVISION HISTORY
    written in 2012, added to SVN in final form on 11 Feb 2013 by LAP
    Error discovered March 19, 2013. The IDL code was not correctly
    using the estimate command is the linear interpolation between
    the two estimates!. Have to change the
    functions the produce the state space matrices and calculate the
    C(z) transfer functions and apply the filter!!!!! - LAP

process_lqg_parameters (ult_make_lqg.pro)

function process_lqg_parameters, v, weird_parm, funky=funky

NAME:
      process_lqg_parameters

PURPOSE:
      LQG helper: Given the vector of parameters stored on disk,
      generate a usable state space model for the system and the LQG
      controller.

EXPLANATION:
      LQG:

Calling SEQUENCE:
      lqg_parms = process_lqg_parameters(v, weird_parm)

INPUT/OUTPUT:
      input v is the lqg_parmvec produced by
      retrieve_lqg_parameters.pro See below for more detail. This is
      just a bunch of numbers which comprises one entry in the
      config file that the AOC reads in.

     input weird_parm is the fractional delay time. Though
     this is an argument, it should only be called with the correct
     value for the system, which is given below in the Example and Notes.

OPTIONAL OUTPUT:
      None.

EXAMPLE:
     lqg_parms = process_lqg_parameters(lqg_parmvec, 1. - (tt_delay_microsecs/this_frame_rate))

DEPENDENCIES:
     only other functions/procedures in this file

NOTES:
    weird_parm if an argument, but there is one correct
    value:
        tt_delay_microsecs = retrieve_value('TT_DELAY_MICROSECS')
        this_frame_rate is frame rate (Hz) of the system.

REVISION HISTORY
    written in 2012, added to SVN in final form on 11 Feb 2013 by LAP
    Error discovered March 19, 2013. The IDL code was not correctly
    using the estimate command is the linear interpolation between
    the two estimates!. Have to change the
    functions the produce the state space matrices and calculate the
    C(z) transfer functions and apply the filter!!!!! - LAP

apply_lqg (ult_make_lqg.pro)

function apply_lqg, mystr, inputsignal, stop=stopflag, onestep=oflag, print=pflag, differentiate=dflag, trun=trunflag, verbose=verbflag, names=nameflag

NAME:
      apply_lqg

PURPOSE:
      LQG helper: Use this to apply an LQG filter to a stream of
      data to see what it calculates. Used for testing
      implementation of LQG in the AOC.

EXPLANATION:
      LQG:

Calling SEQUENCE:
      my_outputsignal = apply_lqg(mystr, inputsignal)

INPUT/OUTPUT:
      First input mystr is an lqg structure which contains the
      description of the LQG filter. (as generated by
      process_lqg_parameters, see code below).

      Second inputsignal is a time series that the filter is applied
      ot. This should be your residual TT error, extracted from telemetry.

      Returns the output of the filter.

OPTIONAL OUTPUT:
      None.

EXAMPLE:
      my_outputsignal = apply_lqg(lqg_parms, inputsignal)

DEPENDENCIES:
     only other functions/procedures in this file

NOTES:


REVISION HISTORY
    Written in 2012. Added to SVN in final version on 11 Feb 2013 by LAP

    Error discovered March 19, 2013. The IDL code was not correctly
    using the estimate command is the linear interpolation between
    the two estimates!. Have to change the
    functions the produce the state space matrices and calculate the
    C(z) transfer functions and apply the filter!!!!! - LAP

glqgp_lookup_vals (ult_make_lqg.pro)

function glqgp_lookup_vals, index, focus=focusflag

NAME:
      glqgp_lookup_vals

PURPOSE:
      LQG helper: this reverses the process of lookup. It goes from
      an index from 0 to 26 for the case, and figures out values for
      the three paramters in parms.txt that specify it.

EXPLANATION:
      LQG:

Calling SEQUENCE:
      vec = glqgp_lookup_vals(index)

INPUT/OUTPUT:
      Input index is a number from 0 to 26.

      Output vec is a three-element vector containing keyword values
      for the three parameters.

      If the index is invalid, will return a single element -1

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     only other functions/procedures in this file

NOTES:


REVISION HISTORY
    Written in 2012. Added to SVN in final version on 11 Feb 2013 by LAP
     ******* MAJOR CHANGE March 22, 2014 by LAP to accomdate how we
     are setting the keywords in parms for both TT and Focus LQG.

glqgp_lookup_case (ult_make_lqg.pro)

function glqgp_lookup_case, ch1_0, ch2_0, ch3_0, info=infoflag, focus=focusflag

NAME:
      glqgp_lookup_case

PURPOSE:
      LQG helper: This looks up the details (vibrations, atmospheric
      model, etc.) for a LQG filter, given the three keyword
      values. This is used to specify the 27 models that we use for
      the 27 different filters!

EXPLANATION:
      LQG: A way to specify and later find out the 27 cases of the
      LQG filter.

Calling SEQUENCE:
      my_struct = glqgp_lookup_case(ch1, ch2, ch3)

INPUT/OUTPUT:
      inputs ch1, ch2, ch3 are the values of the three keywords.

      output is a struct which describes the filter that is used,
      and gives nmuerical values.

 ;;               'integ' - integartor value (e.g. 0.995)
 ;;               'noise' - noise level (power)
 ;;               'vib_hz' - temporal freqs (hz) of common-path vibrations
 ;;               'vib_powers' - power levels (approx mas^2) of the vibrations
 ;;               'ncp_vib_hz' - temporal freqs (hz) of non-common-path vibrations
 ;;               'ncp_vib_powers' - power levels (approx mas^2) of the vibrations
 ;;               'string' - a string which describes the filter.


OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     only other functions/procedures in this file

NOTES:
    ****** this is where you specify the details of the filter in
    terms of vibrations, atmospheric model. etc!!!!! **********

REVISION HISTORY
    Written in 2012. Added to SVN in final version on 11 Feb 2013 by LAP
   8******** major change marcg 22, 2014 to be compliant with using
   both TT and focus LGQ with these paremeters.

ult_make_lqg (ult_make_lqg.pro)

pro ult_make_lqg, stop=stopflag

NAME:
      ult_make_lqg (formerly known as generate_lqg_parameters)

PURPOSE:
      LQG helper: Generate a new parmaeter file for the AOC which
      has the LQG filters specified. This is the code that converts
      from a model to the coefficients that the AOC needs. The
      models themselves are specified above in glqgp_lookup_case

EXPLANATION:
      LQG:

Calling SEQUENCE:
      ult_make_lqg

INPUT/OUTPUT:


OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     only other functions/procedures in this file

NOTES:


REVISION HISTORY
    Written in 2012. Added to SVN in final version on 11 Feb 2013 by LAP

ult_make_mta

pro ult_make_mta, analyze=aflag

NAME:
      ult_make_mta

PURPOSE:
      Makes the Wfr-Twt split MTA given present alignment

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_make_mta

INPUT/OUTPUT:
      write new configuration files to disk. Must reload into AOC.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     fill_out_to_hermitian
     complexmp
     store_value

NOTES:
    This should be used only very rarely!
    The matrix is only used once you restart the AOC code.

REVISION HISTORY
    written in 2011 by LAP.

ult_make_phs_vlt

pro ult_make_phs_vlt, tweet=tweetflag, woofer=wooferflag, tt=ttflag

NAME:
      ult_make_phs_vlt

PURPOSE:
      Saves default voltage-phase calibration files for AOC.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_make_phs_vlt, [/tweet, /woofer, /tt]

INPUT/OUTPUT:
      writes new configuration file(s) to disk. Must restart AOC.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:
     Has the latest Twt special changes as of Feb 2013.

REVISION HISTORY
    written in 2013 by LAP.

ult_make_rotfoc_vectors

pro ult_make_rotfoc_vectors, gain=gainflag, focusscaling=fflag, triangle=tflag, leavealittle=llflag, transpose=transflag

 NAME:
       ult_make_rotfoc_vectors

 PURPOSE:
       This generate the vectors for the modal projection out of
       the slopes that the RTC now does (changed during remediation,
       Feb 2014). THese are specified by Dave in hid documentation.

       THese vectors come in pairs. project and remove. The project
       is used to calculate how much is there. THe remove is then
       used to take that out of the centroids and send it off to
       whereever it goes to. (FOcus is corrected, rotation is sent
       into the dustbin).

****** when you save these, all you have to do is issue a readparms
to get them in use. You DO NOT have to restart the AOC code.


 EXPLANATION:
       LQG: to tell what mode you are running!

 Calling SEQUENCE:
       IDL> ult_make_rotfoc_vectors
       IDL> ult_make_rotfoc_vectors, gain=0.2, integ=0.999

 INPUT/OUTPUT:
      Inputs: takes two flags
      gain=g ;;; the gain for the focus loop
      integ=i ;;; the integrator for the focus loop

       Outputs: does not return anything to IDL session. Does change
       files on disk!

 OPTIONAL OUTPUT:
       None

 EXAMPLE:

 DEPENDENCIES:
      only other functions/procedures in this file

 NOTES:


 REVISION HISTORY
      Written Feb 28, 2014 by LAP.
      Based on calculations for rotation project in ultimate/ult_Get_rotation.pro

ult_make_subapmask

pro ult_make_subapmask, allow1529=aflag, small=smallflag

NAME:
      ult_make_subapmask

PURPOSE:
      Generate the WFS_CAL file of valid subaps.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_make_subapmask, [/allow1529]

INPUT/OUTPUT:
      saves a new WFS_CAL.fits file to the aoc's disk.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:

REVISION HISTORY
    ;; final version. 06-28-2012 LAP

ult_measure_darks

pro ult_measure_darks, quiet=quietflag, log=logflag

NAME:
      ult_measure_darks

PURPOSE:
      Save AO WFS pixel darks.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_measure_darks,[/quiet,log=log]

INPUT/OUTPUT:
      /quiet - Don't print helpful messages
      log - Add string to log file.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_log
     rtc_issue_command

NOTES:
    Does not close loops.  Only takes darks for current frame rate.
    This routine expects the light source to be off.  It does not
    move any mechanisms, so its up to you to do that.

REVISION HISTORY
    written 06-05-2012 LAP
    switch over to using AOC command, plus logging.

ult_measure_dm_flats

pro ult_measure_dm_flats, config=config

NAME:
      ult_measure_dm_flats

PURPOSE:
      Save Woofer and Tweeter flats, with focus term explicitly set
      to woofer.

EXPLANATION:
      Zeros out woofer flat, measures the flat, reconstructs the
      focus and resaves, then measures the tweeter flat.

Calling SEQUENCE:
      ult_measure_dm_flats,[/config]

INPUT/OUTPUT:
      /config - Update the 'WFR_LAB_FLAT' param to config/latestWfrOffset

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     store_value, retrieve_value
     rtc_issue_command
     closeall, openall
     ult_save_dm_flats
     zernmode_generator
     rtc_do_split_ourselves,rtc_do_recombine_ourselves

NOTES:
     This function closes and opens all AOC loops twice.

REVISION HISTORY
    written 12-01-2012 ds based on code by LAP & ST

ult_measure_etf

pro ult_measure_etf, focus=focflag, rot=rotflag, noe=noeflag, zero=zeroflag

No header information available.

ult_measure_fmode_intensity

pro ult_measure_fmode_intensity

NAME:
    ult_measure_fmode_intensity

PURPOSE:
      Place fourier modes on the mirror and measure the phase and
      intensity. This is to study pupil conjugation, as we should
      have no (or minimal) intensity variations.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_measure_fmode_intensity

INPUT/OUTPUT:


OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
      ult_get_intensity
      ult_get_phase

NOTES:

REVISION HISTORY
    written in 2012 by LAP.

ult_measure_parallax

pro ult_measure_parallax

NAME:
      ult_measure_parallax

PURPOSE:
      Measure the parallax (motion of spot due to something not
      being pupil conjugate when it should be).

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_measure_parallax

INPUT/OUTPUT:


OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:
       We really shouldn't need to use this. In fact, we
       discovered that a mispointing of the SF fools this test! See
       online gpilib docs for more details.

REVISION HISTORY
    2011-12-07 by LAP.

ult_measure_refs

pro ult_measure_refs, quiet=quietflag, log=logflag

NAME:
      ult_measure_refs

PURPOSE:
      Measure and store reference centroids.

EXPLANATION:
      Wrapper for AOC measureRefCents command.

Calling SEQUENCE:
      ult_measure_refs[/quiet,log=log]

INPUT/OUTPUT:
      /quiet - Don't print helpful messages
      log - Add string to log file.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_log
     rtc_issue_command
     read_parms

NOTES:
    Use rtc_command_select_references to apply measured centroids.

REVISION HISTORY
    written 06-05-2012 LAP
    switch over to using AOC command, plus logging.

ult_offset_refs_with_rotation

pro ult_offset_refs_with_rotation, rotation_arcmin

No header information available.

ult_save_dm_flats

pro ult_save_dm_flats, quiet=quietflag, log=logflag, twt=twtflag, wfr=wfrflag, lab=labflag, offset=offflag

NAME:
      ult_save_dm_flats

PURPOSE:
      Save Woofer and Tweeter flats

EXPLANATION:
      Wrapper for AOC storeShapes command.

Calling SEQUENCE:
      ult_save_dm_flats,/twt|/wfr,[/quiet,log=log,/lab,/offset]

INPUT/OUTPUT:
      /twt - Save tweeter flat
      /wfr - Save woofer flat
      /quiet - Don't print helpful messages
      log - Add string to log file.
      /lab - Save lab flat (default is system flat)
      /offset - Save as offset to current flat.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_log
     rtc_issue_command
     retrieve_value, store_value

NOTES:
    Files will be saved as System flats (0x2, 0x20) unless /lab is
    specified, then they will be saved as Lab flats (0x1, 0x10)

REVISION HISTORY
    written 06-05-2012 LAP
    switch over to using AOC command, plus logging.

ult_set_dark_corner

pro ult_set_dark_corner, on=on, off=off, status=status

NAME:
      ult_set_dark_corner

PURPOSE:
      Toggle on/off AOWFS dark corner correction.

EXPLANATION:


Calling SEQUENCE:
      ult_set_dark_corner,/on

INPUT/OUTPUT:
      None.

OPTIONAL OUTPUT:


EXAMPLE:


DEPENDENCIES:
     ult_take_ao_darks
     rtc_command_readconfig

NOTES:
    Loops MUST BE OPEN!
    This routine will attempt to put everything back to the state it
    found GPI in.

REVISION HISTORY
    written 08.01.14 - ns

ult_set_focus_mode

pro ult_set_focus_mode, lqg=lqgflag, errout=errout, gain=gainflag, autoselect=aflag

NAME:
      ult_set_focus_mode

PURPOSE:
      Provide an easy way to switch from regular integral control of
      TT to the LQG.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_set_focus_mode [, lqg=casenum]

INPUT/OUTPUT:
     lqg=casenum select the filter from the 27 options (0 to 26).
     Set to -1 or leave null for Integral controller
     Set /autoselect to have it tell the AOC to select the best LQG
     itself. This is done by setting the parameter to -1 when stored
     to parms!

OPTIONAL OUTPUT:
      errout - 1 if error occured

EXAMPLE:
     ult_set_focus_mode  ;;;; back to normal integral controller
     ult_set_focus_mode , lqg=10 ;;; chose case #10
     ult_set_focus_mode, /lqg, /auto

DEPENDENCIES:
     ult_make_lqg ;; for getting the details from the case
     ult_check_focus_mode

NOTES:
    If the casenum is not in the range, glqgp_lookup_vals will
    produce an error. This code will return, having done nothing.


REVISION HISTORY
    written in 2012. Addded to ult by Lisa on 11 Feb 2013.
    04.23.13 - Added errout - ds

ult_set_tt_mode

pro ult_set_tt_mode, lqg=lqgflag, errout=errout, autoselect=aflag

NAME:
      ult_set_tt_mode

PURPOSE:
      Provide an easy way to switch from regular integral control of
      TT to the LQG.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_set_tt_mode [, lqg=casenum]

INPUT/OUTPUT:
     lqg=casenum select the filter from the 27 options (0 to 26).
     Set to -1 or leave null for Integral controller
     Set /autoselect to have it tell the AOC to select the best LQG
     itself. This is done by setting the parameter to -1 when stored
     to parms!

OPTIONAL OUTPUT:
      errout - 1 if error occured

EXAMPLE:
     ult_set_tt_mode  ;;;; back to normal integral controller
     ult_set_tt_mode , lqg=10 ;;; chose case #10
     ult_set_tt_mode, /lqg, /auto

DEPENDENCIES:
     ult_make_lqg ;; for getting the details from the case
     ult_check_tt_mode

NOTES:
    If the casenum is not in the range, glqgp_lookup_vals will
    produce an error. This code will return, having done nothing.


REVISION HISTORY
    written in 2012. Addded to ult by Lisa on 11 Feb 2013.
    04.23.13 - Added errout - ds

ult_setup_onsky

pro ult_setup_onsky

No header information available.

ult_skydarks

pro ult_skydarks

NAME:
      ult_skydarks

PURPOSE:
      Quickly take new AO WFS dark to correct bias drifts while guiding.

EXPLANATION:
      Opens loops, closes shutters, takes AO darks, and re-closes
      loops.  To be used only while guiding.

Calling SEQUENCE:
      ult_skydarks

INPUT/OUTPUT:

OPTIONAL OUTPUT:

EXAMPLES:

DEPENDENCIES:


NOTES:
     could be upgraded to report on how mcuh the darkk has drifted, for
     the morbidly curious

REVISION HISTORY
      Written 4/4/2015 bmac
      Folded into gpilib 4/5/2015 ds

ult_status

pro ult_status

NAME:
      ult_status

PURPOSE:
      Print out info that we need, but isn't in GPIDIAGRAM

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_status

INPUT/OUTPUT:
      lun=lun : pass in a logic unit to make it write to a file
      instead of stdout.
      no outputs

      prints out helpful info to stdout about the TT controller parameters

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_make_lqg.pro to get the details with glqgp_lookup_case


NOTES:



REVISION HISTORY
    Written in 2012. Added to final SVN in ultimate by LAP on 11 Feb 2013.

ult_subtask_sf_raster

function ult_subtask_sf_raster, delta_xy, xy_offset, nmoves=nmoves, total_intensity=total_intensity

NAME:
      ult_subtask_sf_raster

PURPOSE:
      Helper function for ult_task_sf_center.  Raster's SF
      stage to find the light.

EXPLANATION:
      Move SF stage in a grid.  Fit 2D gaussian to the results, and
      interpolate to find peak of the gaussian.

Calling SEQUENCE:
      res =  ult_subtask_sf_raster(delta_xy,xy_offset [,nmoves=nmoves,total_intensity = total_intensity])

INPUT/OUTPUT:
      delta_xy - Size of each move (in mm).
      xy_offset - Current offset to add to all moves
      nmoves - Number of moves (defaults to 5)

OPTIONAL OUTPUT:
      total_intensity - Intensity values at each grid location.

EXAMPLE:

DEPENDENCIES:
     tlc_command_sf
     ult_get_intensity

NOTES:

REVISION HISTORY
    Written 12/03/12 - ds based on code by LAP

ult_sysalign

pro ult_sysalign, guide=guide, source=source, att=att, asu_pos=asu_pos, lightonly=lightonly, aomag=aomag, calmag=calmag, obsmode=obsmode, zenith=zenith, ttlqg=ttlqg, foclqg=foclqg, observer=observer, nodarks=nodarks, newflats=newflats, focoff=focoff, noaligncheck=noaligncheck, useidlcent=useidlcent, nosf=nosf, nocent=nocent, centerpin=centerpin, noquestions=noquestions, nolqgset=nolqgset, usecalsphereintelsim=usecalsphereintelsim, noifsimage=noifsimage, errout=errout

NAME:
      ult_sysalign

PURPOSE:
      System alignment

EXPLANATION:
      Everything you need to do to get the beam through a
      coronagraph and onto the IFS

Calling SEQUENCE:
      ult_sysalign,[options]

INPUT/OUTPUT:
     /guide - User will be guided through the alignment with a
              series of questions.  If this keyword is not set, the
              systems assumes you know what you are doing and goes by
              the flags set.  If set, ALL other flags are ignored.

     source - 'ASU'|'TELSIM' If unset, will try to automatically
              detect based on current laser/shutter settings. The
              TELSIM is no longer in use, so this setting is for
              historical purposes only.
     att - Attenuation level (defaults to 25.5 dB)
     asu_pos - If set, overrides default ASU position with input
               value (see tlc_move_source for input format)
     /lightonly - Return after setting up source.

     aomag - AO I magnitude to use for configuration (defaults to
             4.0)
     calmag - CAL H magnitude to use for configuration (defaults to
              0.0)
     focoff - Closed loop focus offset in nm RMS (defaults to -50,
              set to 0 to not apply any).
     obsmode - Observation mode.  See tlc_obsmode for possible
               settings, or set to 'None' to stop at the CAL.
     zenith - GPI's zenith angle in degrees (defaults to 90)
     ttlqg,foclqg - LQG case number (-1 for integral controller).
             Currently defaults to autoselect where AOC determines
             best LQG mode.
     observer - Observer name to pass to start_us_up and
                set_my_idl_mode

     /nodarks - Do not take new AO WFS darks
     /newflats - Take new DM flats
     /noaligncheck - Skip apodizer & lyot alignment checks
     /nosf - Skip checking the SF alignment.
     /nocent - Do not realign AO WFS to MEMS (will use previous best
               centering).
     /useidlcent - Use IDL WFS to MEMS routine (defaults to
                  instrument sequencer version)
     /nolqgset - Do not set the LQG mode
     /centerpin - Run centerpin after doing alignFPM (skipped by default)
     /noquestions - Don't query user about turning on components or
                    running start_us_up - just do it.
     /usecalsphereintelsim - Assume that the TELSIM is being fed by
                             the CAL sphere (no longer applicable).
     /noifsimage - Do not take an IFS image at the end of
                   alignment.  A 60 s IFS frame is taken by default
                   if a coronagraphic mode is used.

OPTIONAL OUTPUT:
      errout - 1 on error condition

EXAMPLES:
     ;hand-holding
     ult_sysalign,/guide

     ;just get some light
     ult_sysalign,/lightonly,source='ASU',att=25

     ;quick and dirty AO alignment up to the CAL
     ult_sysalign,obsmode='None',/nocent

     ;thorough AO alignment
     ult_sysalign,band='None'

     ;full system alignment (will leave system aligned and tracking
     ;    on the FPM)
     ult_sysalign,obsmode='H_coron',source='ASU'


DEPENDENCIES:
     All of the ult_task* routines, all of gpilib

NOTES:
    If you want to turn on the light yourself, do this (otherwise
    the code will do it for you):
    If laser is powered down, do:
       tlc_move_power,'super_continuum',/on
       wait,5
       tlc_move_source,/asu,/init
    Once laser is warmed up, make sure AO components are powered on
       tlc_move_power, /on, ['MEMS', 'woofer', 'ao_tt']
    To use ASU:
       tlc_move_source,asu_pos='deploy',sc_pow=100,sc_att=25,sphere_att=60.
    For TelSim:
       tlc_move_source,asu_pos='extract',shutter='open',sc_pow=100,sc_att=60.,sphere_pos=24.,sphere_att=25
    Set up your idl session to talk to the AOC
       start_us_up, /mode_ifs


REVISION HISTORY
      Written, 11/15/2012. st & ds
      (extensively revised by ds)
      default SC source brightness changed by bmac 1/23/13 to
      reflect new SC source
      07.12.13 - Added check for OL models - ds
      04.05.15 - Added focus offset - ds
      07.01.15 - made sure sets lqg=1 for TT and dark
                     corner off for now - bmac
      10.21.16 - Open AO loops @ end.  MEMS2TWT default to IS - vpb
      12.8.16 - flatall at end. sf=2.8 for all. vpb

ult_take_ao_darks

pro ult_take_ao_darks, errout=errout

NAME:
      ult_take_ao_darks

PURPOSE:
      Turn off all light sources, save AO WFS pixel darks, return
      GPI to original state.

EXPLANATION:
      Wrapper for ult_measure_darks

Calling SEQUENCE:
      ult_take_ao_darks

INPUT/OUTPUT:
      None.

OPTIONAL OUTPUT:
      errout - 1 if error occurs, 0 otherwise

EXAMPLE:


DEPENDENCIES:
     ult_measure_darks
     rtc_issue_command

NOTES:
    Loops MUST BE OPEN!
    This routine will attempt to put everything back to the state it
    found GPI in.

REVISION HISTORY
    written 08.13.14 - ds

ult_task_align_apod

function ult_task_align_apod, pupdark, band=band, memshape=memshape, maxaxis=maxaxis, minaxis=minaxis, nomove=nomove, ppm0=ppm0, gain=gain, mxerr=mxerr, checkonly=checkonly, numcoadds=numcoadds

NAME:
      ult_align_apodizer
PURPOSE:
      Align apodizer to mems.

EXPLANATION:
      Calculate initial offset, and then iterate in closed loop
      until you match desired tolerance.

Calling SEQUENCE:
      ult_align_apodizer,apodizer

INPUT/OUTPUT:
     band - Name of apodizer to use (e.g., 'H').  See
                tlc_move_apodizer for details.
     ppm0 - Rotation & offset to use (can be set instead of band)
     pupdark - Dark frame.
     memshape - Mems poke to use.  If not set, will default to
                rotated symmetric poke.
     gain - Loop gain.  Defaults to 0.5.
     mxerr - Convergence tolerance in pixels (defaults to 0.5).
     checkonly - Just run a check, do not iterate.

     output - 2x1 array of centering for apodizer: [offset,
              rotation] in mm and degrees. These are the absolute
              (not relative) settings to the filter wheel.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     pupalign

NOTES:


REVISION HISTORY
      Written, 04/10/2012. savransky1@llnl.gov
      11.14.12 - updated to match new sysalign code - ds

ult_task_align_lyot

function ult_task_align_lyot, lyot=lyot, pupdark=pupdark, memshape=memshape, gain=gain, mxerr=mxerr, maxAxis=maxAxis, checkonly=checkonly, nomove=nomove, numcoadds=numcoadds, retstruct=retstruct, maxiniterr=maxiniterr, scalefac=scalefac

NAME:
      ult_align_lyot
PURPOSE:
      Align lyot to mems.

EXPLANATION:
      Calculate initial offset, and then iterate in closed loop
      until you match desired tolerance.

Calling SEQUENCE:
      res = ult_task_align_lyot(lyot=lyot,pupdark=pupdark,.../retstruct)

INPUT/OUTPUT:
     lyot - Name of lyot mask to use, i.e., '080_02'.  See
            tlc_move_ifs for details.
     pupdark - Dark frame.
     memshape - Mems poke to use.  If not set, will default to
                rotated symmetric poke.
     gain - Loop gain.  Defaults to 0.5.
     mxerr - Convergence tolerance in pixels (defaults to 0.5).
     checkonly - Just check alignment, don't run iteration
     maxiniterr - Maximum allowable initial error in pixels (RSS).
                  Defaults to 10.  This is to prevent spurious
                  initial measurements, but may increased if the
                  Lyot is actually that far off for some reason.

     res - 1 for success 0 for failure. If /retstruct is set,
           returns output from pupalign.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     pupalign

NOTES:


REVISION HISTORY
      Written, 04/10/2012. savransky1@llnl.gov
      11.14.12 - updated to match new sysalign code - ds

ult_task_breakdown_pinhole

pro ult_task_breakdown_pinhole, att0, sf_size, cal_exit, before_state=before_state, leave_mirrors=lmflag, errout=errout, verb=verb, debug=debug, drkcrnstat=drkcrnstat

NAME:
      ult_task_breakdown_pinhole

PURPOSE:
      Restore SF to pri-pinhole settings

EXPLANATION:
      Undoes ult_task_make_pinhole

Calling SEQUENCE:
      ult_task_breakdown_pinhole,att0,sfsize,cal_exit,[before_state=before_state,/leave_mirrors,drkcrnstat=drkcrnstat]

INPUT/OUTPUT:
      /leave_mirrors - By default, all mirrors are initially
                       flattened, and then returned to their
                       original state after the SF has been
                       aligned.  If this keyword is set, the
                       alignment is done with the mirrors at their
                       current states.

OPTIONAL OUTPUT:
      errout

EXAMPLE:


DEPENDENCIES:
     tlc_move_cal
     tlc_move_source
     tlc_command_sf
     apply_active_state

NOTES:

REVISION HISTORY
    Written 8/13/14 - ds

ult_task_center_acts

pro ult_task_center_acts, useaoc=useaoc, option=option, leave_mirrors=lmflag

NAME:
      ult_task_center_acts

PURPOSE:
      Zero out centering between AO WFS lenslets and MEMS actuators.

EXPLANATION:
      Runs simple closed loop to zero out meeasured centering offset
      using AO PnC mirrors.  Results are stored in the default for
      the AO PnC mirrors.

Calling SEQUENCE:
      ult_task_center_acts,[/useaoc,option=option]

INPUT/OUTPUT:
      /useaoc - Use AOC function to measure centering offset
      option - Shape to use for measurement (see
               ult_get_centering_acts_lenslets fro details).
      /leave_mirrors - If set, no optics are moved or loops closed
                       prior to alignment

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_get_centering_acts_lenslets
     tlc_command_pnc_pc
     rtc_command_close_loops,rtc_command_open_loops
     get_active_state, apply_active_state

NOTES:
     This functionality is now handled by the instrument sequencer
     (wrapper function ult_task_center_acts_is).  This function is
     retained for debugging purposes.

REVISION HISTORY
    Written 2012/12/02 by LAP

ult_task_center_acts_is

pro ult_task_center_acts_is, verb=verb, debug=debug, errout=errout

NAME:
      ult_task_center_acts_is

PURPOSE:
      Zero out centering between AO WFS lenslets and MEMS actuators.

EXPLANATION:
      Wrapper for instrument sequencer function MEASURE_TWT_LENS

Calling SEQUENCE:
      ult_task_center_acts_is

INPUT/OUTPUT:
      /verb - Toggle verbosity

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     tlc_find_binary
     tlc_query_ao_pnc
     tlc_query_ao_centoff
     tlc_move_helper
     save_default_pnc_pc

NOTES:

REVISION HISTORY
    Written 2012/12/16  - ds

ult_task_center_pupil

pro ult_task_center_pupil, hold_dms=dflag

NAME:
      ult_task_center_pupil

PURPOSE:
      Zero out centering between AO WFS lenslets and telescope pupil.

EXPLANATION:
      Runs simple closed loop to zero out meeasured centering offset
      using the inputfold.  Results are stored in the default for
      the inputfold mirrors.

Calling SEQUENCE:
      ult_task_center_pupil

INPUT/OUTPUT:
      None.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_get_centering_pupil_lenslets
     tlc_command_inputfold
     get_active_state, apply_active_state
     save_default_inputfold

NOTES:
     This functionality is now handled simply by putting the
     inputfold in track and applying pupil offsets from the AOC.
     This function is retained for debugging purposes and as an
     independent check.

REVISION HISTORY
    Written 2012/04/27 by LAP

ult_task_make_pinhole

pro ult_task_make_pinhole, phsize=phsize, phatt=phatt, att0=att0, sfsize=sfsize, cal_exit=cal_exit, drkcrnstat=drkcrnstat, before_state=before_state, leave_mirrors=lmflag, checkonly=checkonly, perr=perr, errout=errout, verb=verb, debug=debug

NAME:
      ult_task_make_pinhole

PURPOSE:
      Create a pinhole

EXPLANATION:
      Irises down the SF to a 0.01 mm pinhole & flood illuminates.

Calling SEQUENCE:
      ult_task_sf_center,[/leave_mirrors]

INPUT/OUTPUT:
      /leave_mirrors - By default, all mirrors are initially
                       flattened, and then returned to their
                       original state after the SF has been
                       aligned.  If this keyword is set, the
                       alignment is done with the mirrors at their
                       current states.
      /checkonly - Make a pinhole, but don't try to align it (record
                   misalignment in return var perr).
      phsize - Size of pinhole in mm
      phatt - Initial attenuation to try

OPTIONAL OUTPUT:
      errout - 1 if error occurs, otherwise zero.
      att0 - Original attenuation before starting
      sfsize - Original SF opening size before starting
      before_state - AO mirror state before starting
      drkcrnstat - Dark corner correction status
      perr - Alignment error

EXAMPLE:


DEPENDENCIES:
     run_readwrite_query
     tlc_move_cal
     tlc_move_source
     tlc_command_sf
     ult_get_pointing
     ult_task_point
     ult_subtask_sf_raster
     get_active_state, apply_active_state

NOTES:
     This function will automatically try to get you into a good
     light range, so the phatt setting is merely a starting point
     and may be changed as needed.

REVISION HISTORY
    Written 2/06/13 - ds
    Updated 03.07.13 with changes to ult_task_sf_center - ds
    Updated 05.12.13 added ult_set_dark_corner to turn off dark
    corner correction before starting - ns

ult_task_point

pro ult_task_point, leave_mirrors=lmflag

NAME:
      ult_task_point

PURPOSE:
      Zero out tip/tilt error as measured by the  AO WFS using the
      AO tip/tilt mirror.

EXPLANATION:
      Runs simple closed loop to zero out meeasured pointing
      error. Save results as current best flattening value.

Calling SEQUENCE:
      ult_task_point

INPUT/OUTPUT:
      None.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_get_pointing
     rtc_command_set_tt
     get_active_state, apply_active_state

NOTES:
     This functionality is essentially the same as closing the
     tip/tilt AOC loop, but is useful in alignments to get current
     tip/tilt flatenning values without closing the loop.

REVISION HISTORY
    Written 2012/03/25 by LAP
    02/06/2013 - added lmflag - ds

ult_task_point_asu

pro ult_task_point_asu, cal=cal, finalpos=finalpos

NAME:
      ult_task_point

PURPOSE:
      Zero out tip/tilt error as measured by the AO WFS or the CAL
      using the ASU.

EXPLANATION:
      Runs simple closed loop to zero out meeasured pointing
      error.

Calling SEQUENCE:
      ult_task_point_asu

INPUT/OUTPUT:
      /cal - Use CAL measurement (defaults to AO WFS measurement)

OPTIONAL OUTPUT:
      finalpos - resulting asu position setting

EXAMPLE:


DEPENDENCIES:
     ult_get_pointing
     tlc_move_source

NOTES:

REVISION HISTORY
    Written 2013/05/07 - ds

ult_task_point_pnc

pro ult_task_point_pnc, nosave=nosave

NAME:
      ult_task_point_pnc

PURPOSE:
      Zero out tip/tilt error as measured by the  AO WFS using the
      AO PnCs.

EXPLANATION:
      Runs simple closed loop to zero out meeasured pointing
      error.

Calling SEQUENCE:
      ult_task_point_pnc

INPUT/OUTPUT:
      /nosave - don't update default

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:
     ult_get_pointing
     tlc_move_source

NOTES:

REVISION HISTORY
    Written 2013/05/07 - ds

ult_task_sf_center

pro ult_task_sf_center, leave_mirrors=lmflag, checkonly=checkonly, errout=errout, perr=perr, outval=outval, phatt=phatt

NAME:
      ult_task_sf_center

PURPOSE:
      Center the beam on the spatial filter.

EXPLANATION:
      Irises down the SF to a 0.01 mm pinhole, flood illuminates,
      and the zeros out the measured tip/tilt by moving the SF x/y
      stage.  If the beam does not hit the initial pinhole, the SF
      is rastered in a grid until the light is found.

Calling SEQUENCE:
      ult_task_sf_center,[/leave_mirrors,/checkonly]

INPUT/OUTPUT:
      /leave_mirrors - By default, all mirrors are initially
                       flattened, and then returned to their
                       original state after the SF has been
                       aligned.  If this keyword is set, the
                       alignment is done with the mirrors at their
                       current states.
    /checkonly - Do not change the target position of the SF.  Try
                 to get an error estimate, but do not correct it.
                 If the SF is so misaligned that there's no light on
                 the AO WFS when pinholed, the pointing error will
                 return as all zeros.

OPTIONAL OUTPUT:
      errout - 1 if error occurs, otherwise zero.
      perr - Final pointing error
      outval - Array written to log_sfpos_err: [perr, X target, Y
               target, X motor pos, Y motor pos, SF stage temp]

EXAMPLE:


DEPENDENCIES:
     run_readwrite_query
     tlc_move_cal
     tlc_move_source
     tlc_command_sf
     ult_task_make_pinhole
     get_active_state, apply_active_state

NOTES:

REVISION HISTORY
    Written 12/03/12 - ds based on code by LAP
    03.08.13 - offloaded making pinhole to ult_task_make_pinhole
    07.01.15 - modified to not turn dark corner on for now (bmac)

ls_modhdr (ult_telem.pro)

pro ls_modhdr, hdr, newinfo

ult_telem_save (ult_telem.pro)

pro ult_telem_save, res, offset=oflag, subap=subflag

ult_telem (ult_telem.pro)

pro ult_telem, sec=secflag, gainreport=gflag, tag=tag, etf=etfsetflag

NAME:
      ult_telem

PURPOSE:
      fast dump of data for residuals on TT, DMs

EXPLANATION:
      see above.

Calling SEQUENCE:
     lisa_res, sec=num

INPUT/OUTPUT:
      sec=num is the number of seconds over which to take data. This
      enforces a minimum of 5.5 seconds (one large data dump). Any
      input under 5.5 will result in 5.5 seconds. No upper limit.

prints out the tag. Does not process at all - that's on Lisa's
                                              laptop
        OPTIONAL OUTPUT:
      tag - Time stamps of data set

EXAMPLE:


DEPENDENCIES:



REVISION HISTORY
    written in 2012 by LAP.

ult_ttlqg_final_set

pro ult_ttlqg_final_set, index, integ, noise, vib_alphas, vib_hz, vib_powers, ncp_vib_hz, ncp_vib_powers, mystring, framerate, fix37=fix37flag

FINAL LQG filters sets, as of Sep 2014.

Jan 29, 2015 - added in a flag to set it to fix 37 Hz.

ult_tweak_mta

pro ult_tweak_mta, analyze=aflag, stop=stopflag

NAME:
      ult_tweak_mta

PURPOSE:
      Evaluates the gain on the Wfr modes via MTA and adjusts as necessary.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_tweak_mta

INPUT/OUTPUT:
      may write new configuration files to disk. Must reload into AOC.

OPTIONAL OUTPUT:
      None.

EXAMPLE:


DEPENDENCIES:

NOTES:
    Usualy when this is run the gains are all one and you
    don't actually change the MTA at all!.


REVISION HISTORY
    written in 2011 by LAP.

ult_twt_leak_map

pro ult_twt_leak_map, uniform=uflag, leak=lflag, poor=poorflag, deadnei=dnflag

NAME:
      ult_twt_leak_map

PURPOSE:
      Make the variable-leak Twt map to improve performance with
      spatial filter and edge actautors.

EXPLANATION:
      see above.

Calling SEQUENCE:
      ult_twt_leak_map, [uniform=gain, leak=gain]

INPUT/OUTPUT:
      gain is the value, e.g. 0.995, for the integrator for all
      acts.
      leak is the value, e.g. 0.995, for most of the acts when we do
      some to be extra leaky. Those are always set to 0.9

OPTIONAL OUTPUT:
      None.

EXAMPLE:
      ult_twt_leak_map ;; make the default
      ult_twt_leak_map, uniform=0.995 ;; all are 0.995
      ult_twt_leak_map, leak=0.995 ;; most are 0.995, deadnei and poorly are defaults (0.9)
      ult_twt_leak_map, leak=0.995, poor=0.995 ;; only deadnei are 0.9
      ult_twt_leak_map, leak=0.995, deadne=0.99 ;; deadnei are 0.99, poorly 0.9 still
      ult_twt_leak_map, leak=0.99, dead=0.99, poor=0.99 ;;; same es uniform=0.99


DEPENDENCIES:

NOTES:
     In practice you call this with no arguments to get the default
     best map!

REVISION HISTORY
    written in 2011 by LAP.

ult_wferms

function ult_wferms, nframes=nframes, display=display, filename=filename, graph=graph, avphase=avs, zernike=zernikeflag

NAME:
      ult_wferms

PURPOSE:
      Function to quickly spit out the average RMS WFE (actuator by
      actuator) through a GPI dataset

EXPLANATION:
      Uses the recovered 'phase' variable (which is the FT of the
      AOC-dumped phase) - should be equal to sum of woofer and
      tweeter phase

Calling SEQUENCE:
      res = ult_wferms([nframes=nframes,/display,filename=filename,/graph,avphase=avs)

INPUT/OUTPUT:
      nframe - Number of frames to dump (defaults to current frame
               rate)
      /display - Graphically display results
      /graph - Plot phase as a function of time
      /zernike - display zernike fits to avg phase

OPTIONAL OUTPUT:
      filename - On return will contain the filename of the phase
                 dump data
      avs - 2D time-averaged phase (48x48)

EXAMPLES:

DEPENDENCIES:
     zernikefit
     rtc_retrive_dumpdate

NOTES:
    to fix: display behaviors; look for efficiency through avg / stddev

REVISION HISTORY
      Written by bmac at some point
      Folded into gpilib 4/5/2015 ds
      vpb added log file output 11/2016