Overview of Routine Operations

As mentioned in the discussion of Scheduled Calibrations , observers do not need to take afternoon cals. It is, in fact, discouraged as getting consistent cals at consistent times is important for the long term modeling of the instrument behavior. If observers want custom calibrations, they should discuss this well ahead of time with their assigned SA and the KPF Instrument Scientist.

Thus observers will first interact with the instrument controls sometime around or just before sunset. Once they have launched the VNC sessions, they should start the GUIs (see Start GUIs section below) and then run the start of night script (see Run Start of Night section below).

Start GUIs

The KPF GUIs can be launched from the FVWM menu from KPF Control Menu → Start KPF GUIs or via the kpfStartGUIs script on the command line. The GUIs can be launched at any time and starting them does not affect instrument operations.

Run Start of Night

The next thing observers should do is run the Start of Night script (KPF Control Menu → Run Start of Night Script on the FVWM menu or kpfStartOfNight on the command line). This script will configure the AO bench so it should only be run if the AO bench is not in use.

In addition, the Start of Night script will configure certain DCS keywords, so it will only do this if KPF is the selected instrument. If KPF is not the selected instrument, the script will do other tasks, but this must be re-run to properly configure DCS before observing.

Typical Observing

A typical observing sequence will consist of:

1. Observer highlights their chosen target in Magiq and asks the OA to slew.

2. Observer opens (or builds from scratch) an OB for the target and executes it. This can and should be done during the slew. Executing the OB will pre-configure the guider settings based on the target info in the OB, so that it is in a reasonable starting configuration for the OA to acquire the target. This will save time on sky under normal observing conditions.

3. The OA acquires the target to the KPF PO and closes the tip tilt loops and notifies the observer that the loops are closed.

4. It is likely that the OB script has been waiting for confirmation to proceed at this point, if so, the observer can hit Enter to proceed and the system will begin taking data.

5. At the end of the OB, the loops will be opened by the script and the observer can then start the process for the next target by highlighting it in Magiq.

Split Night Handoff

Between KPF-KPF splits, the observers should set the program ID keyword so that data is ingested by KOA properly. This is done using KPF Control Menu → Set Program ID and Observers in the FVWM menu (or via command line using kpfSetObserverFromSchedule). This checks the telescope schedule and sets both program ID and observer names. If there is more than one KPF program scheduled, it will ask which to set.

You can set these values manually using kpfSetObserver and kpfSetProgram on the command line if the telescope schedule query is not working or if you need a custom value.

KPF does not change the output directories on split nights as KOA is the primary way to get the KPF raw and L0 data.

Simultaneous Calibrations

The observers have the option in the OB to take “simultaneous calibrations” which will direct calibration light (typically from the Etalon) to a fiber which makes up one of the traces in the pseudo-slit.

It is important that the flux in the simulcal trace be well chosen. If the simulcal trace is much brighter than the target star, then the distant wings of the PSF and/or scattered light can contaminate the science traces and bias the RV measurement.

To adjust the brightness of the simulcal trace, two sets of neutral density filters are available. The filters in the two wheels in the calibration bench can be stacked to generate a variety of fluxes. As of this writing, there is not a system to automatically choose those values. Thus unless the observers are very confident that they know how to balance this, we are currently discouraging use of simulcal.

Slew Cals

During the night (especially in the absence of simultaneous calibrations) we encourage users to take “slew cals” periodically. The KPF OB GUI has a timer in the upper right corner which keeps track of the time since the last slew cal. We recommend taking a slew cal roughly every hour, thus that timer turns orange at 1 hour and red at 2 hours.

The observers should take a slew cal using the “Execute OB with Slew Cal” button on the OB GUI (as opposed to the “Execute This OB” button). If the observers execute the OB at the start of the slew, then the slew cal will cause a minimal delay in observing the next target.

While the slew cal is being taken, the FIU hatch is closed and the fold mirror is put in place, so the OA will see two calibration fibers (point sources) slide in to the guider field during calibration, then they will slide out when the slew cal is done. The observer should notify the OA that they are taking a slew cal, so that the OA does not inadvertently try to acquire one of these calibration sources to the pointing origin using Magiq.

Ca H&K Spectrograph

Unless disabled in the OB, KPF will obtain a Ca H&K spectrograph exposure at the same time as the main KPf spectrograph (using the same exposure time). This is valuable for monitoring stellar activity, but is not directly used for RV measurements.

Exposure Meter

The exposure meter can have two different roles depending on how the observer has chosen to configure the OB. The primary role is to sample the stellar flux during the exposure and use that to derive the flux weighted exposure midpoint time for barycentric velocity correction. Thus we almost always want to have the exposure meter running during science exposures. There is an option in the OB to set the ExpMeterExpTime value automatically based on the catalog G magnitude of the target. This is recommended.

If the exposure meter exposure time is too short, the flux will be low in each sub exposure. This will lead to potential problems as the detector in the exposure meter appears to have a floating bias level and so given the large extraction area used (the trace is very “tall” on the detector), a small error in the bias subtraction can lead to a very large flux error. Sometimes this makes the fluxes negative in one or more channels (often the blue channel).

Saturating the pixels of the exposure meter will obviously also cause problems. There is an NSATURATED keyword which indicates how many pixels are saturated in the most recent exposure meter image to be analyzed. That keyword is also reported in the exposure meter GUI along the top.

One important thing to be aware of about the exposure meter is that if you look at the raw FITS images, the sky trace will be brighter than the star trace. This is because the exposure meter has its own sky fiber, but it is getting only a small fraction of the science light.

Limitations of the OB GUI

The OB GUI, in its current implementation, does not support all features of the underlying OB. If using the OB GUI to build or execute a science OB, only a single “observation” is supported. In principle an OB can be built (e.g. a .yaml file written) which contains multiple “observations”. In practice, this is rarely used for science. The OB GUI contains its own internal data model for an OB which truncates at a single science observation, so it can neither build nor execute a multi-observation science OB.

For calibration OBs, the OB GUI does support limited multi-observation OBs, but only the very limited set of up to two dark observations (e.g. a bias and a dark), and one calibration observation (which uses a cal lamp). Again, the internal data model for an OB truncates anything beyond those limited cases. This is important to know because the daily scheduled calibration OBs typically have multiple observations and so will not work if executed from the GUI.

To execute a fully featured OB, simply use one of the command line tools such as kpfRunCalOB or kpfRunSciOB and feed the script an appropriate OB (in .yaml file format) as input.

Tip Tilt System

The tip tilt system for KPF is surprisingly complex. The camera is controlled by the kpfguide service, which takes the stream of images and does several things with that image data.

Basic Camera Controls

The most fundamental controls of the guide camera are the frames per second (kpfguide.FPS), the gain (kpfguide.GAIN), and whether the software is making the image stream available (kpfguide.CONTINUOUS). Technically, I think there are ways to separately modify the individual frame exposure time and frames per second such that the camera would run at a slower FPS than what the frame exposure time would naively allow, but we don't do this in practice. The kpfguide service also provides controls and telemetry for the camera cooling system.

The Image Stream for MAGIQ

The kpfguide service produces an image stream output for use by Magiq. This stream stacks individual exposures and simulates a more typical guiding exposure cadence. It outputs FITS files to kpfguide.OUTDIR and can be turned on and off by kpfguide.SAVE. The simulated exposure time is controlled by kpfguide.EXPTIME while the stacking is controlled by kpfguide.AVERAGE and kpfguide.STACK. This stream is used for human consumption (images displayed in the Magiq GUI) and for initial target identification and acquisition. It is not used for guiding. Because of this, I recommend using “long” exposures (at least 1 second, but I suggest using 2-4 seconds). This minimizes the number of FITS files written to disk which saves on disk space and CPU use. Using exposure times of under a second can overly burden the system and so it has been disabled at the keyword level.

The Trigger File

Another file output from kpfguide is the so called “trigger file”. When the kpfguide.TRIGGER keyword is set to Active, it begins accumulating full speed telemetry and (possibly) images. When kpfguide.TRIGGER is set to Inactive, it takes the telemetry and images and writes them out to a file in kpfguide.TRIGOUTDIR. If the kpfguide.TRIGCUBE keyword is Active, then it includes an image cube of every image taken at the full frame rate of the camera. If kpfguide.TRIGCUBE is inactive, the FITS file only contains header info, a simple stacked image (similar to the Magiq output), and a table of the system telemetry. Writing out the full cube of images is computationally expensive and can overload the system if used on exposures more than about 10-20 seconds in length. As a result, this feature (using kpfguide.TRIGCUBE=Active ) should only be done by expert users.

The main use of the trigger file is for telemetry only ( kpfguide.TRIGCUBE=Inactive ). This telemetry is included in every science image (assuming “Guide” in included in the value of kpfexpose.TRIG_TARG). The L0 file assembled by kpfassemble contains several HDUs generated from the trigger file.

The Tip Tilt Correction Loop

Object Detection and Deblending

For each image that comes in from the guide camera (at the full frames per second rate), object detection is performed using source extractor (technically, we use the python SEP package). The kpfguide.OBJECT_INTENSITY keyword controls the extraction threshold in sep.extract. It can be thought of as the number of sigma above the background noise for a pixel to be marked as a potential detection. The kpfguide.OBJECT_AREA control the minarea input in sep.extract which is the minimum number of adjacent pixels which must be above the detection threshold in order to be a detection.

The source extractor code also “deblends” detected objects to, for example, separate merged stellar images. The primary control for this is the kpfguide.OBJECT_DBCONT value.

For more detailed discussion on detection, deblending, and operational advice, see Tip Tilt Instructions for OAsarchived .

Object Identification

After objects have been detected, we need a system to maintain a consistent identity for each star from frame to frame. Source extractor might detect a star in one frame, but the same star falls beneath the threshold in the next. Maintaining identifications is done through a series of heuristics which have evolved over time.

The most important things to know about this process are: 1) that it is not infallible, and 2) you can get some information about the quality of the identifications by looking at the kpfguide.OBJECTn keywords (where n is 1, 2, or 3). Those keywords contain 4 pieces of information about each detected star:

It is important to note that these values are not updated on a per frame basis, but are meant to represent the last ~1 second of time. The x and y position and the flux are an average, weighted by exponential decay of the values. The fourth value (“hits”) is effectively the fraction of frames in which this star was detected. The -999 values indicate that no star is currently detected (the above example was extracted when the system was inactive).

Tip Tilt Corrections

Once the objects have been detected and identified, one is selected to be the target (kpfguide.OBJECT_CHOICE). That star is then driven to the target pixel by sending commands to the fast tip tilt mirror located on the PCU stage.

Offloading to the Telescope

Periodically (at a cadence set by kpfguide.OFFLOAD_PERIOD), the tip tilt mirror position is assessed. If the mirror position is away from its home by more than kpfguide.OFFLOAD_MARGIN, then an offload command is sent to the telescope. This is akin to sending a normal telescope guiding command and ensures that the tip tilt mirror stays within its valid range of motion.

Offloading to the telescope can be enabled and disabled using the kpfguide.OFFLOAD keyword. In addition, the system checks whether KPF is the selected instrument (kpfguide.OFFLOAD_DCS) and will disallow offloading if it is not. This is regardless of the state of kpfguide.OFFLOAD, so for offloads to occur, both kpfguide.OFFLOAD and kpfguide.OFFLOAD_DCS must be “Active”.

Pointing Origins

The kpfguide system contains code which allows the target pixel to be adjusted for various factors.

The “pointing origin” is reflected in the kpfguide.CURRENT_BASE value which gets updated based on the selected pointing origin in DCS. Note that the positions of the science and sky fibers are stored separately (kpfguide.SCIENCE_BASE and kpfguide.SKY_BASE). In normal operations, kpfguide.CURRENT_BASE will match kpfguide.SCIENCE_BASE. In principle, we can use this system to direct the starlight to the sky fiber, but in practice this has never been done and the position of the sky fiber has not been accurately measured (at least not to the ~0.1 arc second level that the science fiber has).

The pointing origin, however, is not where we want the star to be driven to. Because the guide system is using longer wavelength light (950-1200 nm) than the science arm (the ADC has a 550 nm zero deviation wavelength) we need to account for differential atmospheric refraction (DAR) between the two.

DAR Correction

If kpfguide.DAR_ENABLE is “Yes”, then the system will add the vector in kpfguide.DAR_OFFSET to the kpfguide.CURRENT_BASE pixel position to derive the target pixel. The offset is constantly updated based on the telescope pointing position. Note that when pointing very low (e.g. when parked at EL=0), the target pixel is not on the CRED2 detector.

Offset Guiding

Code exists within kpfguide to add another vector in to the target pixel calculation which can be used to guide on a target which is not the science target. This is not yet a tested and released mode.

Guiding Using MAGIQ

It is possible to guide using MAGIQ and not engage the tip tilt control in kpfguide, however this is not recommended. MAGIQ is unaware of the need for DAR correction, so it will not place the star on the required target pixel.

To achieve something like telescope guiding, we can bypass the tip tilt mirror and have kpfguide only use telescope offloads to steer the star. This can also be used if one or both of the tip tilt mirror axis is non-functional. This mode is controlled by the kpfguide.TIPTILT_CONTROL_X and kpfguide.TIPTILT_CONTROL_Y keywords.

Non-standard Observation Types

Raw Image Display in ds9

For non-standard observing programs (basically anything that is not a stellar PRV measurement), there are a few things to consider. Because most PRV measurement programs will primarily look at the reduced data via the CPS Team’s “Jump” tool, they rarely examine the raw images displayed in ds9. Programs which do examine the raw images in ds9 need to be aware of two factors.

First, the image display is only one of the two amplifiers, so you’re only seeing half the chip. This is a limitation of how the Archon controller writes the headers. The headers do not include sufficient information for ds9 to demosaic them and display the full field.

Second, the KPF detectors are read out in 32-bit format. This means the data do not exist on a 0-65,535 range as we are used to. To translate the data to a sensible format use the follow rules of thumb:

• Divide the raw ADU value in ds9 by 65,536. This will put the data in to a “normal” 0-65,535 ADU range.

• To get an estimate of electronics, multiply by 5 (the approximate gain).

• The detectors are approximately linear up to <150k electrons which is 30,000 in the traditional ADU scale and about 2e9 in the raw ADU reported by ds9.

• The bias offset is ~4e7 in raw ADU counts.

Offset to Sky Observations

Some types of observations may want to get separate sky frames. This can also be the case if the sky fiber happens to land on a nearby star and compromises the sky measurement. If a separate sky measurement is needed, the observers can obtain one manually by asking the OA to offset to a chosen position and then executing an OB for the sky observation. For a sky observation, the observers should set the GuideMode to off so that the tip tilt system does not try to put a star on the fiber.

Block Sky Option

The sky fiber is fixed in the instrument plane relative to the science fiber. During observations, a background object may fall on to the sky fiber. If the interloper is bright, scattered light or the wings of the PSF on the detector may fall on to the science traces and contaminate them. If this is a concern, OBs have a BlockSky option and the OB GUI surfaces this as a checkbox. Turning this on will close the source select shutter for the sky fiber and mitigate any concerns about contamination.

Software

Translator Software Development and Deployment

mwhich

Because most of the KPF “scripts” are part of the KPF Translator and not the usual shell scripts, the mwhich tool works differently for KPF. It will try to determine where the requested command is from and will show either the shell script or the python source code if it is a Translator function.

Grafana