modules.cross_correlation

KPF Cross-Correlation module.

Cross-correlates each order of an extracted, wavelength-calibrated, barycentric-corrected KPF L2 against a line mask to produce per-order cross-correlation functions (CCFs). Produces a KPF4 (L4) holding the per-order CCFs, their per-bin photon variances, and the per-order metadata table the radial-velocity step later fills with fitted RVs.

Each fiber’s mask, barycentric handling, and CCF grid center are dispatched from its illumination source (SCI-OBJ/SKY-OBJ/CAL-OBJ in INSTRUMENT_HEADER):

source mask barycorr grid center target TARGTEFF-lookup yes TARGRADV (systemic) sky G2_espresso (solar) yes 0 thar ThAr list (unit wt) no 0 etalon / lfc skipped (no CCF; not implemented) none not illuminated -> skipped (no CCF)

All reference wavelengths (stellar line masks, ThAr line list) are in vacuum; no air/vacuum conversion is performed.

class kpfpipe.modules.cross_correlation.CrossCorrelation(l2_obj, config=None)

Bases: object

Compute per-order cross-correlation functions from a KPF2.

Parameters:

  • l2_obj (KPF2) – Extracted L2 frame. Must have per-fiber FLUX and WAVE arrays populated (by SpectralExtraction and WavelengthCalibration) and the per-order barycentric correction extensions populated by BarycentricCorrection.

  • config (None | dict | ConfigHandler) – Module configuration. Recognized keys: chips, fibers, ccf_mask_width, ccf_step_size, ccf_window.

compute_ccfs(chip, fiber, mask_width=None, step_size=None, window=None, clip_edge_pixels=(500, 500))

Cross-correlate every order of one chip/fiber against the line mask.

Parameters:

  • chip (str) – Chip identifier, i.e. ‘GREEN’ or ‘RED’.

  • fiber (str) – Fiber identifier, e.g. ‘SCI1’.

  • mask_width (float, optional) – Per-line mask top-hat width [km/s]. Defaults to the configured value.

  • step_size (float, optional) – CCF velocity step size [km/s]. Defaults to the configured value.

  • window (list of float, optional) – CCF velocity grid range [km/s] as [min, max] about the grid center. Defaults to the configured value.

  • clip_edge_pixels (tuple of int, optional) – Number of pixels to drop from the (short_wavelength_end, long_wavelength_end) of each order before correlating, removing the blaze-faint, low-S/N order edges. Defaults to (500, 500).

Returns:

{‘velocity’, ‘ccf’}: the CCF velocity grid [km/s] and the CCF with shape (norder_chip, n_velocity_step). The CCF is also cached under f’{chip}_{fiber}’. Returns None if the fiber is not illuminated (source ‘none’).

Return type:

dict or None

Raises:

  • ValueError – If BARYCORR_Z is required (astronomical source) but not populated.

  • NotImplementedError – If the fiber’s illumination source has no CCF path yet (etalon, lfc).

info()

Print a summary of the module configuration and CCF results.

perform(chips=None, fibers=None, *, ccf_mask_width=None, ccf_step_size=None, ccf_window=None, clip_edge_pixels=(500, 500))

Compute per-order CCFs and package them in a KPF4.

For each illuminated orderlet (fiber), the per-order CCFs of both chips are written to the orderlet’s CCF cube ({fiber}_CCF, green+red concatenated) and their per-bin photon variances to {fiber}_CCF_VAR (same shape). The orderlet’s RV table ({fiber}_RV) is seeded with its per-order metadata (ORDER_INDEX/ORDER_ID/ECHELLE_ORDER/BJD_TDB/BERV/WAVE_START/ WAVE_END/WEIGHT); the RV/RV_ERR columns are left NaN for RadialVelocity to fill.

Parameters:

  • chips (list of str, optional) – Chip identifiers, i.e. ‘GREEN’ or ‘RED’. Defaults to the configured chips.

  • fibers (list of str, optional) – Fiber identifiers, e.g. [‘SCI1’, ‘SCI2’]. Defaults to all configured fibers (SCI, CAL, and SKY).

  • ccf_mask_width (float, optional) – Per-line mask top-hat width [km/s]. Overrides the configured value.

  • ccf_step_size (float, optional) – CCF velocity step size [km/s]. Overrides the configured value.

  • ccf_window (list of float, optional) – CCF velocity grid range [km/s] as [min, max] about the grid center. Overrides the configured value.

  • clip_edge_pixels (tuple of int, optional) – Pixels to drop from the (short_wavelength_end, long_wavelength_end) of each order before correlating. Defaults to (500, 500).

Returns:

l4_obj – L4 with a CCF cube, a per-bin CCF variance cube, and a metadata-seeded per-order RV table per illuminated orderlet. Each CCF extension carries CTYPE1/CTYPE2/VELSTART/VELSTEP/VELNSTEP/CCFMASK/VELMASK; each RV extension carries CTYPE1/CTYPE2. Unilluminated (‘none’) or not-yet-implemented (etalon, lfc) fibers are skipped (empty extensions).

Return type:

KPF4