Instrument Overview

Instrument Layout

Here’s a simple block diagram showing the locations of major components throughout the observatory.

Open

A conceptual layout showing where things are located at the observatory. The arrows indicate major light paths or other significant connections. Note that no attempt has been made to indicate the cal light path to keep this simple.

KPF has a presence throughout the facility. The lines in the diagram above indicate some critical connection (typically light, but a liquid nitrogen is also shown) is flowing between the locations. No attempt has been made to make the above diagram a comprehensive flow chart of where fibers carry the science or calibration light.

Descriptions of Selected Subsystems

FIU

See the KPF Web Page section on the FIU.

Agitator

See also the KPF Web Page section on the Agitator.

The agitator is located in the crypt beneath the K1 azimuth axis. The crypt has been designated a “Permit Required Enclosed Space” while there is LN2 in the basement (anytime KPF is cold). This means we can not access this area without substantial safety precautions.

Exposure Meter

See the KPF Web Page section on the Exposure Meter.

Cal Bench

See the KPF Web Page section on the Cal Bench.

Scripts

KPF is operated using “Observing Blocks” (OBs). Observers build an OB which describes their observation an then the OB is executed using a script. There are currently two types of OBs: Science and Calibration.

Science OBs are described on the KPF web page. Observers will typically not need to build Calibration OBs as KPF is calibrated every day via cron job (see the Scheduled Calibrations section below).

OBs can be executed via a command line script. The script is part of the KPFTranslator and can be executed using: kpfdo RunSciOB -f [filename]. The kpfdo command is how translator scripts are executed. The RunSciOB script (like all of the most used scripts) is aliased to the command kpfRunSciOB to make it easier to type with tab completion, so kpfRunSciOB -f [filename] . In both cases [filename] should be replaced with the OB file (a .yaml file).

OBs can also be executed via the KPF OB GUI, but see the section below on the limitations there.

Calibration OBs can be executed in a similar manner using the kpfRunCalOB script.

The Script Keywords

It is important that only one script be run at a time to avoid scripts sending conflicting commands. To manage this, we have a set of keywords which are part of the kpfconfig service:

• SCRIPTNAME - Records the filename of the script (e.g. RunCalOB.py)

• SCRIPTPID - Records the process ID of the script

• SCRIPTHOST - Records the user and host where the process is running (e.g. kpfeng@kpfserver)

• ALLOWSCHEDULEDCALS - Enables or disables scheduled (cron) execution of calibrations. See the Scheduled Calibrations section below.

Running OBs

The scripts which execute OBs (currently only RunSciOB and RunCalOB) have similar structures. They are composed of several steps.

For a Calibration OB, these steps are:

1. ConfigureForCalibrations - Configures the instrument for calibrations. Primarily, this turns on the specified lamp and sets the FIU in to calibration mode.

2. Loops over all dark and bias sequence elements in the OB and runs ExecuteDark

3. Loops over all cal lamp sequence elements in the OB and runs ExecuteCal

4. CleanupAfterCalibrations - Cleans up. Primarily this turns off lamps and sets the FIU to “Stowed”.

For a science OB these steps are:

1. ConfigureForAcquisition - Configures the instrument for target acquisition. Sets the guider exposure parameters based on the OB and sets the FIU to “Observing” mode.

2. Waits for user to indicate that the OA has acquired the target and tip tilt loops are on.

3. ConfigureForScience - Configures the instrument for a science observation. Among other things, this sets which detectors will be in the exposure based on the OB.

4. Loops over all science sequence elements in the OB and runs ExecuteSci

5. CleanupAfterScience - Cleans up. Primarily this stops the tip tilt system and the agitator (if needed).

Stopping Scripts

If a script is in progress and you want to stop it, we recommend against using ctrl-c or similar tools to kill a process (unless of course it is truly frozen). To stop a script in a gentle way, so that the script cleans up after itself properly (i.e. it runs the cleanup steps described above), set the kpfconfig.SCRIPTSTOP keyword to “Yes”. Script for which this makes sense, will include periodic checks of this keyword and if it is found to be “Yes”, the script will exit and perform cleanup.

The kpfconfig.SCRIPTSTOP functionality will not terminate a running exposure and the script will not check the SCRIPTSTOP keyword status until after the exposure is complete. To terminate a running exposure, set kpfexpose.EXPOSE to “End” and also set kpfconfig.SCRIPTSTOP. There are buttons on the KPF OB GUI for each of these two actions.

Open

Screenshot of the KPF OB GUI showing the “Request Script Stop” Button and the “STOP Exposure and Script” button.

Enabling and Disabling Lamps and Detectors

If there is a problem with a detector sub-system or with one of the calibration sources, we can disable that sub-system for the scripts. This means that the observers don’t have to edit their OBs and then edit them back based on whether the system is performing.

There are kpfconfig.%_ENABLED keyword for the various detectors and lamps. In addition, there is a kpfconfig.USEAGITATOR keyword which serves the same purpose for the agitator. If set to “No”, the scripts will not use the associated subsystem during observations.

Here is the full set of kpfconfig keywords which enable or disable a component:

Coordination of Detector Systems: kpfexpose

The multiple detector systems within KPF (red, green, Ca HK, exposure meter, and to a lesser degree the guider) are sequenced via the kpfexpose keyword service. For the main science detectors (red and green), accurate timing is vital to getting good radial velocity measurements. As a result, the red, green, and Ca HK detectors are all set up to use an external trigger signal which is provided by a galil board. Furthermore, the shutters are also actuated by galil (again with accurate timing measurements). It is the kpfexpose service which sequences all of this.

Within kpfexpose one can select which detectors will be triggered using the TRIG_TARG keyword and the detector subsystems (e.g. kpfgreen, kpfred, and kpf_expmeter) will be managed appropriately.

An exposure can be triggered (and stopped) using the kpfexpose.EXPOSE keyword by setting it to “Start” or “End” appropriately. In order for an exposure to be started, the value of kpfexpose.EXPOSE must be “Ready”. This status reflects the status of the selected detector subsystems. The keywords EXPLAINR and EXPLAINNR give some explanation of why the EXPOSE keyword is either “Ready” or is not “Ready” respectively.

The kpfexpose.EXPOSE keyword gives the current state of an exposure was well. Under normal exposure conditions it will transition from “Ready” to “Start” to “InProgress” to “Readout”, then back to “Ready”.

This sequencing is complex, especially once you include the exposure meter which can be taking many short exposures during the single long science exposure. Not every race condition has been tracked down and eliminated yet. We will occasionally see kpfexpose.EXPOSE go to a state which is seemingly out of the normal sequence. This is usually benign, but can cause occasional problems. One nuisance possibility is that the instrument sounds may see “Readout” briefly (thanks to the exposure meter state) near the start of an exposure and trigger an early “Readout Complete” sound. This can be ignored if the sound is the only symptom.

L0 File Assembly

Each detector writes out a raw file to disk. Each has its own OUTDIR which we set to a subdirectory of the typical date directory. For example, the /s/sdata1701/kpfeng/2024jan08 data directory contains subdirectories:

• CaHK for the Ca HK detector.

• CRED2 for the guide camera (more on that in the Guide Detector Outputs below).

• ExpMeter for the exposure meter.

• FVC1, FVC2, and FVC3are for the outputs of the Fiber Viewing Cameras (FVCs), but these are not used in normal operation.

• Green for the green detector.

• Red for the red detector.

The L0 sub-directory contains the assembled Level 0 (aka “Raw”) frames. When the instrument takes data which is sequenced by kpfexpose, the kpfassemble service picks up the individual frames from the directories listed above and assembles them in to a multi-extension FITS file.

With one exception, the L0 file (which uses the KOA file naming conventions) contains all of the raw data, so none of the component files are needed once the L0 file has been created. We keep those around for a while, so that we can regenerate the L0 after the fact in case of trouble.

The exception to the above principle is the exposure meter. Because keeping the raw exposure meter frames would take a lot of disk space, what is included in the L0 file for the exposure meter is the output of the “micro DRP” which analyzes the raw frames (see the Exposure Meter Output Files section below).

Exposure Meter Output Files

Each raw exposure meter frame has a filename like kpf_em_FRAMENO.SEQNUM.fits where “FRAMENO” is the 6 digit frame number (kpf_expmeter.FRAMENO) which increments on the main science camera exposure, not on an exposure meter exposure and “SEQNUM” is a 3 digit sequence number which increments on each exposure meter frame (it resets to 1 when FRAMENO increments).

Thus during a single science exposure which generates many exposure meter exposures, a set of exposure meter files with the same FRAMENO and with a range of SEQNUM values will be created.

The exposure meter “micro DRP” will analyze the individual frames and extract 1D spectra from each. The results are put in to a separate FITS file named kpf_em_FRAMENO.fits which contains only a FITS table of 1D spectra. It is this FITS table which is pulled in to the L0 file by kpfassemble.

Guider Detector Output Files

The guide detector (a CRED2) is constantly exposing at a fixed frame rate; the default is 100 Hz. This frame rate is controlled by the kpfguide.FPS keyword; this frame rate must be high to meet the needs of the tip/tilt control loop. Though exposures are always happening, the image stream is not broadcast to other software unless the kpfguide.CONTINUOUS keyword is set to 'Active'.

The Slow Image Stream for Magiq

In order to have compatibility with Magiq, the kpfguide software creates an output image stream for Magiq which is used for acquisition (and can be used for Magiq guiding if desired, but see discussion on the Night Support section). The kpfguide.SAVE keyword controls whether these files are written out and the kpfguide.OUTDIR keyword controls where these files are written to and Magiq can set the kpfguide.EXPTIME to get a simulated exposure of the desired length. The detector will still run at the rate specified by kpfguide.FPS, but it will either stack or average the individual frames (according to the kpfguide.STACK and kpfguide.AVERAGE keywords) to build a FITS file which is written to OUTDIR and seen by Magiq.

The TRIGGER File Output

During normal science operation, the fast image stream (e.g. at 100 Hz) is averaged to form an image which is integrated over the science exposure. This is done using the kpfguide.TRIGGER keyword which is set to Active to begin the “exposure” and set Inactive to end it.

The output file is sent to kpfguide.TRIGOUTDIR and contains multiple extensions. The first FITS extension is the average image over the duration of the trigger. The second FITS extension contains a FITS table with metadata about the tip tilt corrections (if active) at the full frame rate of the camera.

The TRIGCUBE Output

If a trigger file is taken while kpfguide.TRIGCUBE is set to Active, then the system will store and write out an image cube containing the subframe of the image (set by kpfguide.WINDOW) which is used in the tip tilt calculation. This goes in to the third FITS extension of the trigger output file as described above.

Please note: full image cube output is extremely costly in computer resources and is not recommended for use except in engineering contexts. Taking a full image cube of duration longer than about 10 seconds can crash software and hang the server depending on conditions.