KPF: Pre-Observing | Observing | Post-Observing
Tip Tilt Instructions for OAs
- Josh Walawender
This page has been superseded by the instructions on the main KPF Web Page which covers the new (June 2024) Tip Tilt GUI.
This page is intended to give guidance to OAs or observers on how to run KPF’s tip tilt correct system.
TL/DR Procedure
Acquire the star to the KPF PO using magiq
In the KPF Tip Tilt GUI, turn on the tip tilt calculations
Check that an object has been selected, if not, select the appropriate object as the guiding target
Check that the peak flux is sufficient.
The value is color coded as a guide, but we’ll need to build up some experience with the thresholds, so don’t take those colors as firm limits.
If there are clouds, you may want a higher peak flux in case you get more extinction during the exposure.
If needed, adjust the guide camera gain and FPS to achieve a better peak flux, but try to keep the FPS as high as possible as this will yield better science.
Saturation is somewhere around 14k. A bit of saturation should not be a problem, but staying a bit under 14k if that’s feasible is a good idea.
If the peak flux is not updating, make sure the “Calculations” checkbox is checked (this can be done without the control loops being active)
Start the tip tilt loops using the “Tip Tilt On/Off” button (all four checkboxes to the right should become checked)
You can turn on and off the individual loops with the 4 checkboxes. If the main “Tip Tilt On/Off” button is ever problematic, you can use those 4 checkboxes.
Briefly check that the system is working. Just a quick glance is fine before moving on, but keep an eye on the items below during the exposure to learn the system.
The RMS value below the mirror positions plot should go to a number at or below about 50mas (may be higher with bad seeing, a faulty tip tilt drive mechanism, or a faint star)
The star should end up very near the KPF PO on magiq, but it may be a few pixels off thanks to differential atmospheric refraction (DAR)
Watch the “Detected Objects” info panel. If the selected object is changing or is coming and going, you may need to adjust the detection parameter. See the Deblending and Star Selection Advice section below if needed.
If this is a double star, make sure the correct star is being steered to the PO. See the Deblending and Star Selection Advice section below.
Let the observers know they can start their exposure
Tip Tilt Overview
The KPF tip tilt system takes fast (e.g. 100 FPS) subframe images from the KPF CRED2 guide camera in order to control the fast tip tilt mirror which directs light in to the KPF FIU. This fast tip tilt system maintains the stellar position on the science fiber. This is critical not for reasons of maximizing flux in to the spectrograph (thought that is a side benefit), but to optimize the radial velocity measurement.
Even after fiber scrambling and agitation, if the star’s position on the fiber entrance fiber shifts, that can manifest as a small shift of the spectrum on the detector which would be interpreted as a radial velocity change. Thus we need to position the star on the fiber, and then hold it in a consistent place during observations and make that position consistent from observation to observation.
To start the GUI, open a terminal as any kpf user (e.g. kpfeng) on the kpf machine and type: tt_gui.
Tip Tilt System Keywords
The tip tilt system is primarily controlled by keywords in two services: kpfguide and kpffiu. The kpfguide service interacts with the CRED2 guide camera, performs the tip tilt calculations, determines the commands to send, and handles offloading to the telescope. The kpffiu service contains keywords which control the tip tilt mirror.
Tip Tilt GUI
The tip tilt GUI can be launched from a KPF machine using kpf start tt_gui, it can also be directly invoked with /kroot/rel/default/bin/tt_gui.
The GUI is divided in to several tabs.
Status and Control Tab
The Status and Control Tab provides interface to the main system controls appropriate for most situations.
Tip Tilt Phase: The top line shows the tip tilt “phase” (kpfguide.TIPTILT_PHASE). This is a good way to tell at a glance is the system is operating. If the phase is “Tracking” then the system thinks it has locked on the target and is successfully controlling the position. Other phase values such as “Idle”, “Identifying”, and “Acquiring” and described in the help of the above keyword and in the mouseover tool tip in the GUI.
Tip Tilt FPS: This value shows the frames per second that are being analyzed by the control loop. When things are working well this should be close to the FPS value for the camera shown below. It is common for this value to vary a bit, but it should stay near the camera FPS. The color of the box will become red if this value differs from the camera FPS by more than 10%. In the screenshot above it is red because the calculations are turned off (the system is not active), so the value is 0.
Tip Tilt On/Off: The next row contains a button which turns the tip tilt loops completely on or completely off (kpfguide.ALL_LOOPS). The components which make up the full list of loops are listed to the right. Calculations (kpfguide.TIPTILT_CALC) indicates whether object detection is running and providing data. Control (kpfguide.TIPTILT_CONTROL) indicates if the system is using the results of calculations to send command to the tip tilt mirror. Offloads (kpfguide.OFFLOAD) indicates whether the system is attempting to offload accumulated error from the tip tilt mirror to the telescope. Finally, DCS (kpfguide.OFFLOAD_DCS) indicates whether the system should be permitted to offload to the telescope. Essentially this is checking whether KPF is the selected instrument.
Peak Flux and Total Flux: The next row shows the flux values from the calculations if they have found a star. The peak flux (kpfguide.OBJECT_PEAK) is showing the peak pixel value in the object while total flux (kpfguide.OBJECT_FLUX) is showing the total summed over all pixels in the detected object.
The peak flux is color coded to indicate when flux is low. Yellow indicates the flux is low, but likely sufficient if no clouds further reduce flux. Red indicated that the flux is extremely low and likely indicates a problem.
Beware that the peak flux value can be impacted by a single hot pixel, so use your judgement and look at the images in magiq. If the peak flux is saturated, but the star looks faint, you probably have a hot pixel in the object.
Camera Gain and Camera FPS: These two fields provide control the the guide camera gain (kpfguide.GAIN) and frames per second (kpfguide.FPS). Changing these will affect the counts in the peak and total flux results.
Detection Parameters: The Detect SNR (kpfguide.OBJECT_INTENSITY) and Detect Area (kpfguide.OBJECT_AREA) values control two of the object detection algorithm's inputs. The system uses the Source Extractor software via the SEP python wrapper. The system detects an object if there are Detect Area contiguous pixels which all have values Detect SNR times the background noise.
Detected Objects: This status is meant to show whether there are multiple objects detected in the images without requiring the user to click over to the Star Selection tab. The “Object 1”, “Object 2”, and “Object 3” text field will be grayed out if no such object is detected. They will be normal text if detected and they will be bold text if that object is the one being used for tip tilt guiding.
If the detection status is changing rapidly (e.g. one of the detected objects is coming or going a lot), then it is likely that the detection or deb lending parameters need to be changed. How to change them will depend on whether the user thinks an object should be getting detected or not.
Axis Control: Due to problems with the tip tilt stage, we sometimes need to disable one xis of the stage and only use telescope offloads. This status shows whether each axis is being controlled by the tip tilt mirror (at the Camera FPS rate) or by telescope offloads (which will be much slower).
DAR Corrections: This indicated whether differential atmospheric refraction (DAR) correction to the target pixel has been enabled or disabled. It should be enabled under typical science use scenarios. The text s color coded green if enabled and red if disabled to highlight that.
Instrument Status: The bottom status bar shows a summary of the instrument status. (Note: the color codes for values in the screenshot above are likely to change). This bottom bar is visible in all three tabs.
The first field shows the FIU mode (kpffiu.MODE). If "Observing" is not listed, this indicates that the guide camera may not be seeing the sky. For example, if it is in "Calibration" mode, it is likely seeing calibration light injected from the basement.
The second field shows the exposure status (kpfexpose.EXPOSE). This is a synthesis of several detectors in the system, but you can think of it is indicating whether a science exposure is in progress or reading out.
The last field shows whether a script is running (kpfconfig.SCRIPTNAME). If one is running, the system is likely about to perform more actions. If it shows None or '' (empty string) the system is likely not in use.
Mirror Position Plot: The right hand plot shows the position of the tip tilt mitt in its range. During operation points will be added to the plot and slowly fade to give a sense of how hard the system is working (how far is has to move from point to point) and whether is has sufficient range to compensate for the seeing and tracking errors.
Star Selection Tab
If multiple stars are detected, they will be shown here. The left plot will show up to 3 symbols indicating where the brightest 3 stars detected by source extractor are. This detection is limited to the small subframe that is being used for tip tilt correction (typically 128 pixels or about 7 arcsec across), so not all stars visible in the full frame image on Magiq will be shown here. The detected stars will be indicated by a blue circle, a green triangle, and a red x. Which star is the guide target can be chosen in the table to the right by selecting the appropriate radio button.
Deblending Parameters: After object detection, Source Extractor performs a “deblending” step in which it attempts to separate objects in to components. This has benefits and perils for our use case. The Deblend Thresh (kpfguide.TIPTILT_DBTHRESH) value is how many brightness layers the object is divided in to in order to search for “valleys” between adjacent bright areas. The Deblend Contrast (kpfguide.TIPTILT_DBCONT) is the required contrast between the peak and a valley in order to split the object in to multiple objects.
Offset Guiding: Offset guiding is not yet supported.
Position Error Graph Tab
Star Selection and Multiple Stars
TL/DR Procedure for Multiple Stars
Acquire the desired star to the KPF PO using magiq
Using the Star Selection tab, confirm that the individual stars seen on the Magiq image are also detected by the KPF tip tilt system.
Note, the tip tilt system keeps a list of at most 3 stars, so if you have a very crowded field, only the three brightest are tracked. This is a fundamental limitation of the system. If you want to observe the fourth brightest star in the field, we can not use the tip tilt system to position it.
If you are not detecting a star you expect to see (especially if it is the science target or is blended with the science target), we need to get the system to detect it.
If the star is likely blended with another, use the deblending contrast parameter to get consistent detection of the desired star (see the Deblending section below).
If the star is not detected at all, try increasing the flux (e.g. by increasing gain or decreasing FPS) and then see if it is detected.
Once you see a marker for the desired target star in the Star Selection Tab’s plot, check that it is the selected star using the radio buttons to the right of the plot. If it is not selected, select it.
Note that if you change the selected star, the tip tilt system will try to move it to the target pixel. These fast movements can sometimes confuse the star identification process. We’re working on this, but it may be necessary to try this a few times, perhaps even starting again by positioning the star using Magiq.
Deblending
As mentioned above, deblending can be both perilous and useful. Early in the system’s use, we were still using the default deblending contrast of 0.005, which meant that it took only a small dip in flux (0.5%) for two adjacent maxima to be considered two different objects. In practice, this meant that a single star would deblend in to multiple stars due to speckles moving about. As a result, the “star” would appear to shift to one side or the other leading to sudden large corrections which would then be reversed a frame or two later when the speckles had shifted and the star was no longer deblended. This could affect several percent of all guide frames (in other words, the star was being jolted around by spurious detections several times per second).
Of course, in situation where there are actually blended stars this is a useful tool. Double stars can be separated and a particular guide target chosen using this system.
Based on very preliminary experience, leaving deblending contrast at 1.0 for most targets is the right choice. This demands that the valley between adjacent peaks be as deep as the highest peak (i.e. it goes to 0), so it turns deblending off. Since most targets are isolated stars with no close neighbors of similar brightness, this avoids the problem of tracking on speckles.
If a double star is the target, decreasing the deblending contrast until it is reliably separates is the best strategy. Compare the detected star positions (in the Star Position plot on the Star Selection tab) to the Magiq guider image to see if it is working – you should see two detected objects if there are two stars visible by eye in the guide image. Keep in mind that the tip tilt system only “sees” a small subframe around the pointing origin. The plot is also in guider pixel coordinates, so it has the same orientation as the Magiq image.
With the system KPF uses, which component you wish to guide on is irrelevant unless the companion is so faint as to render it effectively undetectible. If the stars are blended, they must be deblended for KPF to accurately place one properly on the fiber. If the centroid is biased because the stars are not deblended you will end up with an RV effect due to the positioning of the star on the fiber being incorrect.
The deblend contrast can be run down at 0.005 or lower to pull out a faint companion. Note that this is the contrast between the bright star and the faint "gap" between companions, so large contrast is not unexpected if the companion star is a few magnitudes fainter than the primary. For example, if the deblend contrast is 0.01 that is 5 magnitudes of contrast (2.5*log(0.01)), but that's not an unreasonable contrast for the gap if the companion star is just 2 or 3 magnitudes fainter than the primary.
Also, because the algorithm is doing deblending, not trying to detect the companion as a separate object, we don't need to worry about the primary being too bright -- it is ok to saturate the primary to get the companion.
Of course, a widely separated double star may be seen as two stars by the system if there is a “gap” between the two stars where the signal in the pixels is lower than the detection threshold. In this case, no deb lending is necessary.
Finally, if the star the observers are trying to acquire is too challenging and you are unable to make it work, you can ask the observer to click the "Collect Guider Image Cube" button on their OB GUI. This will save a brief sequence of guider images which can be analyzed offline to find out the best way to acquire that particular star (email the KPF SA to let them know to look at it). This does not help for the immediate observation, but will allow us to find the right solution for the next time this target or a similar one is observed.