modules.masters.wls

KPF Master Wavelength Solution construction module.

class kpfpipe.modules.masters.wls.WLS(l0_file_list, config=None)

Bases: BaseMasterModule

Construct a master wavelength solution from a stack of WLS L0 exposures.

Each frame is processed individually through the L0→L2 pipeline. Fitted line positions across the stack are combined to derive per-fiber wavelength solutions.

Standard reduction: like science, a WLS frame is bias- and dark-subtracted before extraction (_STANDARD_CALIBRATIONS = (“bias”, “dark”)); flat division is part of the standard reduction but stays off until it is implemented.

Parameters:

  • l0_file_list (list of str) – Sorted list of L0 FITS file paths to process.

  • config (None | dict | ConfigHandler) – Module configuration. Recognized keys: linelist, lineprofile, polyorder_x, polyorder_m, polyorder_f, chips, fibers, min_stack_size (per-chip line-fit-QC survivor gate), KPF_MASTERS_OUTPUT.

info()

Print a summary of the module configuration and WLS results.

make_master_l2(l0_file_list=None, *, linelist=None, lineprofile=None, polyorder_x=None, polyorder_m=None, polyorder_f=None, bias=None, dark=None, flat=None, master_path=None)

Build a master wavelength solution from a stack of L0 frames.

Processes each input L0 frame through the L0-to-L2 pipeline, fits per-frame line positions and WLS coefficients (_fit_and_qc_lines_stack), then combines the surviving frames into per-chip Legendre wavelength solutions (_combine_coeffs_stack). The resulting wavelength arrays are written to the per-fiber _WAVE extensions of a KPFMasterL2 object, which is returned and cached on self.ml2_obj. Per-frame diagnostics are always stashed on self._frame_diagnostics; pass master_path to persist the master and, into the thar_L2/ subdirectory beside it, the per-frame L2s and the diagnostics HDF5.

Parameters:

  • l0_file_list (list of str, optional) – L0 files to process. Defaults to self.l0_file_list.

  • linelist (str, optional) – Path to a CSV line list. If different from the currently cached self.linelist, the file is reloaded and the cache is updated. Defaults to self.linelist (no reload).

  • lineprofile (str, optional) – Line profile model name. Defaults to self.lineprofile.

  • polyorder_x (int, optional) – Polynomial degree along the pixel axis. Defaults to self.polyorder_x.

  • polyorder_m (int, optional) – Polynomial degree along the order axis. Defaults to self.polyorder_m.

  • polyorder_f (int, optional) – Polynomial degree along the fiber axis (used for 3- and 5-fiber fits). Defaults to self.polyorder_f.

  • bias (bool | str | KPFMasterL1, optional) – Per-call calibration overrides (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object), clamped by the WLS standard of bias+dark. E.g. dark=False extracts with bias only, and dark=”/path/master_dark.fits” uses a specific master.

  • dark (bool | str | KPFMasterL1, optional) – Per-call calibration overrides (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object), clamped by the WLS standard of bias+dark. E.g. dark=False extracts with bias only, and dark=”/path/master_dark.fits” uses a specific master.

  • flat (bool | str | KPFMasterL1, optional) – Per-call calibration overrides (same forms as ImageProcessing.perform: bool, a master filepath, or a KPFMasterL1 object), clamped by the WLS standard of bias+dark. E.g. dark=False extracts with bias only, and dark=”/path/master_dark.fits” uses a specific master.

  • master_path (str, optional) – If provided, persists the master L2 to this FITS path via save_master(‘L2’, …) and, into a thar_L2/ subdirectory beside it, each processed ThAr frame’s L2 (save_reduced_frames()) and the per-frame diagnostics HDF5 (save_diagnostics()).

Returns:

Master L2 object with per-fiber _WAVE extensions populated for every chip in self.chips, INPUT_FILES recording the stacked L0 files, and a ‘master_wls’ receipt entry.

Return type:

KPFMasterL2

Notes

Resets self._l2_obj_cache before processing so repeat calls do not carry stale frames forward.

Line fitting is attempted for every loaded frame; a frame whose line-fit QC or per-frame fit fails is warned and dropped, never raised. The per-frame L2s and diagnostics HDF5 are written before the survivor gate, so they persist even on gate failure. Raises ValueError if any chip has fewer than self.min_stack_size frames passing line-fit QC (the master is then not written).

save_diagnostics(master_path, *, overwrite=False)

Write the per-frame WLS diagnostics to an HDF5 file in the thar_L2/ subdirectory beside master_path, named {obs_id}_master_thar_diagnostics.h5 (obs_id from master_path).

Layout: /<obs_id>/<chip>/ per input frame and chip, each holding a coeffs dataset (per-frame Legendre coefficients; omitted for a rejected frame), a lines/ group with every key from the per-frame line dict (chip, fiber, index, echelle, wav, pix, std, amp, isgood), and a rejected group attribute flagging whole-frame QC rejection for that chip.

Parameters:

  • master_path (str) – The master L2 output path; its directory anchors the thar_L2/ subdirectory and its obs_id names the file.

  • overwrite (bool, optional) – If False (default), refuse to clobber an existing file and raise FileExistsError. If True, replace any existing file.

Raises:

  • RuntimeError – If make_master_l2() has not been run yet, or raised before populating any chip.

  • FileExistsError – If the file already exists and overwrite is False.

save_reduced_frames(master_path, *, overwrite=False)

Write each processed ThAr frame’s L2 to a thar_L2/ subdirectory beside master_path, as {obs_id}_thar_L2.fits.

Persists the per-frame L2 objects cached by make_master_l2() (every frame that loaded, processed, and extracted), for follow-up ThAr line/WLS-stability analysis.

Parameters:

  • master_path (str) – The master L2 output path; its directory anchors the thar_L2/ subdirectory.

  • overwrite (bool, optional) – If False (default), refuse to clobber an existing per-frame file and raise FileExistsError. If True, replace any existing file.

Raises:

  • RuntimeError – If make_master_l2() has not been run yet, or raised before extracting any frame.

  • FileExistsError – If a per-frame file already exists and overwrite is False.