modules.radial_velocity

KPF Radial Velocity module.

Computes radial velocities from a KPF4 (L4) whose per-order cross-correlation functions were already built by CrossCorrelation. For each illuminated orderlet it fits the per-order CCFs to radial velocities, collapses them into RVs per order, orderlet, and CCD (weighted where appropriate), and fills the results into the L4’s per-order RV tables and headers plus the PRIMARY combined RV.

Everything the fit needs is read from the L4: the CCF cubes (CCFn) and their per-bin variances (CCF_VARn); the velocity grid, reconstructed from each CCFn header (VELSTART/VELSTEP/VELNSTEP); the mask width (VELMASK); and the per-order WEIGHT / BERV / BJD_TDB / WAVE_START / WAVE_END columns of the RVn tables. The native per-pixel velocity scale for the photon error comes from the WAVE endpoints and the detector column count (detector.toml ncol).

class kpfpipe.modules.radial_velocity.RadialVelocity(l4_obj, config=None)

Bases: object

Compute radial velocities from a KPF4’s per-order CCFs.

Parameters:

  • l4_obj (KPF4) – L4 frame carrying the per-order CCFs (CCFn/CCF_VARn), the CCF velocity-grid and mask headers, and the metadata-seeded RVn tables produced by CrossCorrelation. RV/RV_ERR are filled in place.

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

compute_order_by_order_rvs(chip, fiber, window=None, fit_nsigma=3.0, min_npts=9)

Per-order radial velocities for one chip/fiber, from the loaded CCF.

Parameters:

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

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

  • window (list of float, optional) – [min, max] km/s window about the dip for the first-pass fit. Defaults to the configured value.

  • fit_nsigma (float, optional) – Half-width of the second-pass fit window in units of the first-pass sigma. Not a configurable parameter; set in code (default 3.0).

  • min_npts (int, optional) – Minimum number of grid points to use in each fit window. Not a configurable parameter; set in code (default 9).

Returns:

{‘rv’, ‘rv_err’} – length-norder_chip ndarrays [km/s], one per order.

Return type:

dict

Raises:

RuntimeError – If the CCFs have not been loaded for this chip/fiber (call perform() or _load_ccfs first).

compute_weighted_rvs(chips, fibers, combine_fibers, combine_ccds, window=None, fit_nsigma=3.0, min_npts=9)

Weighted-combined RVs from the loaded CCFs, collapsing orders (and optionally fibers and CCDs) into one RV per group.

Orders are always weighted-collapsed (the per-order path is compute_order_by_order_rvs). Two flags control the rest:

combine_fiberssum the three science fibers’ CCFs before collapsing.

True requires fibers == the three SCI fibers; False requires a single fiber.

combine_ccdscombine the per-chip RVs across CCDs at the RV level –

value = order-weight-weighted mean of the per-chip RVs, error = inverse-variance combination.

Per chip, the value comes from fitting the weighted-average CCF and the error from fitting the unweighted-sum CCF (see _combine_ccfs).

Parameters:

  • chips (str or list of str) – Chip identifier(s), i.e. ‘GREEN’ and/or ‘RED’.

  • fibers (str or list of str) – A single fiber, or the three science fibers when combine_fibers=True.

  • combine_fibers (bool) – Sum the three science fibers before collapsing orders.

  • combine_ccds (bool) – Combine the per-chip RVs across CCDs (RV-level weighted mean).

  • window (list of float, optional) – [min, max] km/s window about the dip for the first-pass fit. Defaults to the configured value.

  • fit_nsigma (float, optional) – Half-width of the second-pass fit window in units of the first-pass sigma. Not a configurable parameter; set in code (default 3.0).

  • min_npts (int, optional) – Minimum number of grid points to use in each fit window.

Returns:

combine_ccds=False -> dict {chip: (rv, rv_err)} over chips. combine_ccds=True -> a single (rv, rv_err) tuple [km/s]. A non-finite fit (no order carrying weight) yields (NaN, NaN).

Return type:

dict or tuple

Raises:

  • ValueError – If the combine_fibers flag and fibers are inconsistent.

  • RuntimeError – If the CCFs have not been loaded for any requested chip/fiber.

info()

Print a summary of the module configuration and RV results.

perform(chips=None, fibers=None, *, rv_window=None, fit_nsigma=3.0, min_npts=9)

Fit the per-order CCFs to radial velocities and store them on the KPF4.

For each illuminated orderlet the per-order RVs of both chips are filled into the orderlet’s RV table ({fiber}_RV RV/RV_ERR columns), leaving the CrossCorrelation-seeded metadata columns intact.

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).

  • rv_window (list of float, optional) – [min, max] km/s window about the dip for the first-pass fit. Overrides the configured value.

  • fit_nsigma (float, optional) – Half-width of the second-pass fit window in units of the first-pass sigma. Not a configurable parameter; set in code (default 3.0).

  • min_npts (int, optional) – Minimum number of grid points to use in each fit window. Not a configurable parameter; set in code (default 9).

Returns:

l4_obj – The input L4 with per-order RV/RV_ERR filled per illuminated orderlet. Each RV extension carries RVMETHOD/SKYRMVD/TELLRMVD and the per-fiber legacy CCD<n>RV<sfx>/CCD<n>ERV<sfx>. PRIMARY carries the final science RV: the EPRV RVMETHOD/RV/RVERR/BERV/BJDTDB plus the KPF SCI-combined per-CCD CCD<n>RV/CCD<n>ERV. Fibers with no CCF (unilluminated) are skipped.

Return type:

KPF4