Source code for hispecdrp.primitives.utils.ccf.ccf_utils

"""Cross-correlation (CCF) and radial-velocity utilities.

The canonical overview of the CCF algorithms and conventions lives in the documentation:
``docs/source/algorithms/ccf.rst``.
"""
from __future__ import annotations

import json
import logging
import math
import os
import warnings
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field, replace

import numpy as np
from typing import Any, Literal

from astropy import units as u
from astropy.table import Table
from astropy.modeling import fitting
from astropy.modeling.models import Const1D, Gaussian1D, Polynomial1D

try:
    from astropy.utils.exceptions import AstropyUserWarning
except ImportError:  # pragma: no cover
    AstropyUserWarning = UserWarning
from scipy.ndimage import median_filter, uniform_filter1d
from scipy.signal import savgol_filter
from astropy.stats import mad_std
from pathlib import Path

from hispecdrp.utils.physical_constants import C_M_S
from hispecdrp.utils.line_mask_utils import (
    MaskLineStyle,
    MaskLines,
    pixel_edges_from_wavelength,
    restrict_mask_to_chunk,
    stellar_rv_ccf_mask_lines,
)

from ....datamodels.dqflags import DQ_FLAGS
from ....datamodels.extensions import RVCCF_CCF_ELEM_DTYPE
from ....utils.parallelization_utils import (
    njit,
    numba_thread_scope,
    prange,
    resolve_numba_threads,
)
from .ccf_rv_content import doppler_shift_from_barycenter
from .ccf_bisector import (
    CCFBisectorConfig,
    _refine_ccf_rv_bisector_after_gaussian_fit,
    calc_bisector_inverse_slope,
    fit_ccf_rv_bisector,
)
from .ccf_common import (
    V_MAX_DEFAULT_M_S,
    V_MIN_DEFAULT_M_S,
    V_STEP_DEFAULT_M_S,
    _ccf_background_sigma_clipped_median,
    _ccf_rv_err_numeric_floor,
    _make_velocity_grid,
    effective_ccf_v_step_for_fit,
    resolve_ccf_broad_grid_m_s,
    science_centroid_spec_err,
)


logger = logging.getLogger(__name__)

# =============================================================================
# Module constants (algorithm IDs, line-mask CCF defaults, coarse velocity grid)
# =============================================================================

# Stellar-RV :class:`~hispecdrp.primitives.stellar_rv.stellar_rv_primitive.StellarRVPrimitive`
# ``algorithm`` values that use mask-line CCF (see callers for membership tests).
STELLAR_RV_LINE_MASK_ALGORITHMS: frozenset[str] = frozenset({"ccf_line_mask"})

# Line-mask CCF (``ccf_line_mask``): stored RVCCF / preview CCF rows are negated relative to the
# raw weighted mask statistic when ``flip_rows`` is 1 (always for the current Numba path) so
# the line appears as a maximum near the true RV. Pass ``ccf_line_mask_stored_negated=True``
# to :func:`fit_ccf_rv` when fitting those arrays; see ``diag["ccf_line_mask_stored_negated"]``.
LINE_MASK_CCF_STORED_NEGATED_FROM_RAW = True

# Max Lanczos parameter *a* for mask-line CCF sampling on L2 wavelength pixels
# (``mask_ccf_pixel_interp_order``; stencil spans up to ``2*a`` pixels).
# Default science value is ``3`` (Lanczos-3). ``1`` keeps linear interpolation.
MAX_MASK_CCF_PIXEL_INTERP_ORDER = 8
# Weight buffer length for :func:`_lagrange_stencil_index_and_weights` (Lanczos).
_MAX_PIXEL_INTERP_STENCIL = 2 * MAX_MASK_CCF_PIXEL_INTERP_ORDER

from .ccf_tophat import TOPHAT_MASK_CCF_SEGMENT_SAMPLES
from .ccf_gauss_fit_numba import fit_ccf_rv_rows_numba

# Default coarse CCF velocity grid (m/s) for :func:`resolve_ccf_broad_grid_m_s` when any of
# ``v_min``, ``v_max``, or ``v_step`` are ``None``, and for StellarRVPrimitive coarse kwargs when unset.
# Sub-step biases (~20 m/s) can occur from the grid + Gaussian fit; 50 m/s steps double N_v vs 100 m/s.

# Fractional padding on ``window_size_um`` **full width** for line-mask line-window spectral
# pixels (symmetric about predicted observed line λ at ``ccf_input_velocity``).
LINE_MASK_LINE_WINDOW_SPEC_REL_PAD = 0.02


# =============================================================================
# Line-mask chunking: echelle spans, observed λ windows, mask restriction helpers
# =============================================================================


[docs] def ccf_order_n_chunks_for_span(span_um: float, window_um: float) -> int: """ Number of equal-wavelength segments for one echelle order given a target chunk width. If the order span does not exceed ``window_um``, returns 1 (one chunk = full order). Otherwise returns ``ceil(span_um / window_um)`` so each segment has width ``span_um / n_chunks``, which is at most ``window_um``. Used for mask-line CCF chunking (:func:`rv_per_chunks_line_mask`), template :func:`rv_per_chunks`, and Numba order layouts so chunk counts follow a single rule. See Also -------- :func:`build_line_mask_chunk_wavelength_intervals_line_by_line` — alternate chunking for ``ccf_line_mask`` when ``window_line_by_line`` is true (see :func:`rv_per_chunks_line_mask`). """ if not (math.isfinite(span_um) and math.isfinite(window_um)): return 1 if span_um <= 0.0 or window_um <= 0.0: return 1 if span_um <= window_um: return 1 return int(math.ceil(span_um / window_um))
[docs] def validate_line_mask_line_window_chunking_config( *, algorithm: str, window_line_by_line: bool | None, ccf_input_velocity_m_s: float | None, ) -> None: """ Validate ``window_line_by_line`` against ``algorithm`` and ``ccf_input_velocity``. Raises ------ ValueError If line-by-line chunking is enabled but incompatible with the algorithm, or if ``ccf_input_velocity`` is missing when line windowing is requested. """ if not bool(window_line_by_line): return algo = (algorithm or "").strip().lower() if algo not in STELLAR_RV_LINE_MASK_ALGORITHMS: raise ValueError( "window_line_by_line is only supported for algorithm='ccf_line_mask'; " f"got algorithm={algorithm!r}." ) if ccf_input_velocity_m_s is None or not math.isfinite(float(ccf_input_velocity_m_s)): raise ValueError( "ccf_input_velocity must be set to a finite value (m/s) when " "window_line_by_line is true (grid center defines the Doppler mapping " "used to place mask lines against the spectrum)." )
[docs] def line_mask_line_window_velocity_half_width_m_s( wave: np.ndarray, order_tasks: list[tuple[int, int]], mask_lines: MaskLines, *, v_center_m_s: float, zb: float, min_good_pixels: int, half_width_m_s: float, v_step_m_s: float, ) -> tuple[float, float]: """ Effective half-width (m/s) for a **uniform** centered CCF grid in line-window mode. Returns the caller half-width (floored by a few velocity steps) for :func:`build_centered_uniform_velocity_grid`, plus the maximum Voronoi chunk Doppler span :math:`c\\,\\Delta\\lambda/\\lambda` for logging. The CCF grid is **not** expanded to the Voronoi chunk span: that produced :math:`10^5`--:math:`10^6`-point grids for sparse/line-by-line masks. Per-chunk mask membership still uses :func:`line_mask_chunk_restrict_velocity_range_m_s` with the chunk Δλ. """ v_c = float(v_center_m_s) dv_max = 0.0 for oi, _order in order_tasks: w_row = np.asarray(wave[oi], dtype=np.float64).ravel() wlo, whi, _ctr = build_line_mask_chunk_wavelength_intervals_line_by_line( w_row, mask_lines, v_center_m_s=v_c, zb=float(zb), min_good_pixels=int(min_good_pixels), ) for k in range(int(len(wlo))): lam_m = 0.5 * (float(wlo[k]) + float(whi[k])) d_lam = float(whi[k]) - float(wlo[k]) if lam_m > 0.0 and d_lam > 0.0 and math.isfinite(lam_m) and math.isfinite(d_lam): dv = C_M_S * d_lam / lam_m if math.isfinite(dv): dv_max = max(dv_max, float(dv)) half_w = float(half_width_m_s) pad = max(half_w, 5.0 * abs(float(v_step_m_s))) if not math.isfinite(pad) or pad <= 0.0: pad = half_w if math.isfinite(half_w) and half_w > 0.0 else abs(float(v_step_m_s)) * 5.0 return float(pad), float(dv_max)
[docs] def line_mask_chunk_restrict_velocity_range_m_s( wl_lo_um: float, wl_hi_um: float, *, v_prior_m_s: float, v_span_lo: float, v_span_hi: float, ) -> tuple[float, float]: """ Velocity bounds for :func:`~hispecdrp.utils.line_mask_utils.restrict_mask_to_chunk` on one line-window chunk. Combines the pipeline prior ``v_prior_m_s`` (``ccf_input_velocity``) with the chunk wavelength span :math:`[\\lambda_{\\rm lo},\\lambda_{\\rm hi}]` via :math:`\\Delta v \\approx c\\,(\\lambda_{\\rm hi}-\\lambda_{\\rm lo})/\\bar\\lambda`, intersected with ``[v_span_lo, v_span_hi]`` (already the tightened coarse span when line-window mode is active). """ lam_m = 0.5 * (float(wl_lo_um) + float(wl_hi_um)) d_lam = float(wl_hi_um) - float(wl_lo_um) span = float(v_span_hi) - float(v_span_lo) floor_pad = max(500.0, 0.02 * span) if math.isfinite(span) and span > 0.0 else 500.0 if lam_m > 0.0 and d_lam > 0.0 and math.isfinite(lam_m) and math.isfinite(d_lam): dv = C_M_S * d_lam / lam_m pad = max(floor_pad, 2.0 * dv) if math.isfinite(dv) else floor_pad else: pad = floor_pad v_lo = max(float(v_span_lo), float(v_prior_m_s) - pad) v_hi = min(float(v_span_hi), float(v_prior_m_s) + pad) if not math.isfinite(v_lo) or not math.isfinite(v_hi) or v_hi <= v_lo: return float(v_span_lo), float(v_span_hi) return float(v_lo), float(v_hi)
[docs] def mask_line_window_spectrum_band_um( wl_center_um: float, window_size_um: float, w_min_um: float, w_max_um: float, *, rel_pad: float | None = None, ) -> tuple[float, float]: """ Observed-frame µm interval for spectrum + mask-CCF pixels in line-window line-mask. Band is centered on ``wl_center_um`` (predicted observed mask-line λ at the chunking velocity) with total width ``window_size_um * (1 + rel_pad)``, clipped to the echelle pixel support ``[w_min_um, w_max_um]``. """ wc = float(wl_center_um) wsz = float(window_size_um) if not math.isfinite(wsz) or wsz <= 0.0: raise ValueError("mask_line_window_spectrum_band_um: window_size_um must be finite and > 0") rp = float(rel_pad) if rel_pad is not None else float(LINE_MASK_LINE_WINDOW_SPEC_REL_PAD) if not math.isfinite(rp) or rp < 0.0: rp = 0.0 half = 0.5 * wsz * (1.0 + rp) w0 = float(w_min_um) w1 = float(w_max_um) lo = max(w0, wc - half) hi = min(w1, wc + half) if hi <= lo: return wc, wc return float(lo), float(hi)
[docs] def count_mask_lines_in_observed_wavelength_interval( mask_lines: MaskLines, *, wl_lo_um: float, wl_hi_um: float, v_center_m_s: float, zb: float, ) -> int: """ Count mask line segments with positive weight whose observed λ lies in ``[wl_lo_um, wl_hi_um]``. Uses the same Doppler mapping as :func:`doppler_shift_from_barycenter` at ``v_center_m_s``. """ lam_r = np.asarray(mask_lines.line_lambda_um, dtype=np.float64).ravel() wt = np.asarray(mask_lines.weight, dtype=np.float64).ravel() if lam_r.size == 0: return 0 lam_obs = doppler_shift_from_barycenter(lam_r, float(v_center_m_s), float(zb)) ok = np.isfinite(lam_obs) & np.isfinite(wt) & (wt > 0.0) lam_obs = lam_obs[ok] return int(np.sum((lam_obs >= float(wl_lo_um)) & (lam_obs <= float(wl_hi_um))))
[docs] def build_line_mask_chunk_wavelength_intervals_line_by_line( wave_um: np.ndarray, mask_lines: MaskLines, *, v_center_m_s: float, zb: float, min_good_pixels: int = 10, ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """ Build observed-wavelength chunks with **one mask line per chunk** (Voronoi cells in λ). Mask rest wavelengths are mapped to the observed frame at ``v_center_m_s`` (same as :func:`doppler_shift_from_barycenter`). Distinct observed positions are sorted; each line defines one chunk whose wavelength **window** is the **largest** interval that (i) contains that predicted line λ, (ii) does not overlap neighboring chunks, and (iii) stays inside the pixel wavelength support ``[w_min, w_max]`` of ``wave_um``. Neighbor boundaries are **midpoints** between adjacent predicted line wavelengths (1-D Voronoi cells). Spectrum outside the union of chunks is not analyzed. Chunk **center** wavelengths are each line’s predicted observed λ. The **interval** ``[wl_lo_um, wl_hi_um]`` is a 1-D Voronoi cell between neighbor lines (midpoint boundaries). It is **not** generally symmetric about the line’s predicted λ unless neighbor spacings happen to match. Parameters ---------- wave_um 1-D wavelength samples (µm) for the order. mask_lines Mask lines for the run. v_center_m_s Typically ``ccf_input_velocity`` (m/s). zb Barycentric factor for the Doppler mapping. min_good_pixels Reserved for future filtering when a chunk would contain too few spectral samples. Returns ------- wl_lo_um, wl_hi_um, chunk_center_wavelength_um : np.ndarray Per-chunk bounds (µm) and chunk-center wavelengths (µm). Chunk wavelength half-open convention in :func:`rv_per_chunks_line_mask` matches the last chunk inclusive on the right. """ _ = int(min_good_pixels) # reserved for future pixel-count-based merging of tiny chunks w = np.asarray(wave_um, dtype=np.float64).ravel() w_min, w_max = float(np.nanmin(w)), float(np.nanmax(w)) if not np.isfinite(w_min) or not np.isfinite(w_max) or w_max <= w_min: return ( np.array([], dtype=np.float64), np.array([], dtype=np.float64), np.array([], dtype=np.float64), ) lam_r = np.asarray(mask_lines.line_lambda_um, dtype=np.float64).ravel() wt = np.asarray(mask_lines.weight, dtype=np.float64).ravel() if lam_r.size == 0: return ( np.array([], dtype=np.float64), np.array([], dtype=np.float64), np.array([], dtype=np.float64), ) lam_obs = doppler_shift_from_barycenter(lam_r, float(v_center_m_s), float(zb)) ok = np.isfinite(lam_obs) & np.isfinite(wt) & (wt > 0.0) ok &= (lam_obs >= w_min) & (lam_obs <= w_max) lam_sel = lam_obs[ok] if lam_sel.size == 0: return ( np.array([], dtype=np.float64), np.array([], dtype=np.float64), np.array([], dtype=np.float64), ) # Merge lines that Doppler-map to the same observed wavelength (within tight rtol). lam_sorted = np.sort(lam_sel) if lam_sorted.size >= 2: sep = np.maximum(np.abs(np.diff(lam_sorted)), np.finfo(np.float64).tiny) rel = sep / np.maximum(np.abs(0.5 * (lam_sorted[1:] + lam_sorted[:-1])), 1e-15) keep = np.ones(lam_sorted.size, dtype=bool) keep[1:] &= rel > 1e-9 lam_u = lam_sorted[keep] else: lam_u = lam_sorted n_line = int(lam_u.size) n_per = 1 wl_lo_list: list[float] = [] wl_hi_list: list[float] = [] ctr_list: list[float] = [] for i0 in range(0, n_line, n_per): i1 = min(n_line, i0 + n_per) group = lam_u[i0:i1] lam_first = float(group[0]) lam_last = float(group[-1]) if i0 == 0: lo = w_min else: lo = 0.5 * (float(lam_u[i0 - 1]) + lam_first) if i1 >= n_line: hi = w_max else: hi = 0.5 * (lam_last + float(lam_u[i1])) lo = max(lo, w_min) hi = min(hi, w_max) if hi > lo: wl_lo_list.append(lo) wl_hi_list.append(hi) # Barycenter of predicted observed λ in the group (single line → that line’s λ). ctr_list.append(float(np.mean(group))) return ( np.asarray(wl_lo_list, dtype=np.float64), np.asarray(wl_hi_list, dtype=np.float64), np.asarray(ctr_list, dtype=np.float64), )
[docs] def line_mask_n_chunks_for_order_line_by_line( wave_um: np.ndarray, mask_lines: MaskLines, *, v_center_m_s: float, zb: float, min_good_pixels: int = 10, ) -> int: """Return ``n_chunk`` for one order under :func:`build_line_mask_chunk_wavelength_intervals_line_by_line`.""" wl_lo, wl_hi, _ctr = build_line_mask_chunk_wavelength_intervals_line_by_line( wave_um, mask_lines, v_center_m_s=v_center_m_s, zb=zb, min_good_pixels=min_good_pixels, ) return int(len(wl_lo))
# ============================================================================= # Broad / centered uniform velocity grids and CCF error-propagation helpers # =============================================================================
[docs] def _nanmean_axis0_ignore_empty_columns(arr: np.ndarray) -> np.ndarray: """ Column-wise mean of finite values (axis 0). Columns with no finite entries are NaN. Stacked CCF arrays often have velocity bins where **every** chunk row is NaN; ``np.nanmean(..., axis=0)`` then emits ``RuntimeWarning: Mean of empty slice`` once per such column. This implementation matches ``nanmean`` for mixed finite/NaN columns but avoids that warning. """ a = np.asarray(arr, dtype=np.float64) if a.ndim != 2: raise ValueError("_nanmean_axis0_ignore_empty_columns: expected a 2-D array") n_row, n_col = a.shape if n_col == 0: return np.array([], dtype=np.float64) if n_row == 0: return np.full(n_col, np.nan, dtype=np.float64) fin = np.isfinite(a) cnt = np.sum(fin, axis=0, dtype=np.float64) s = np.nansum(a, axis=0) out = np.full(n_col, np.nan, dtype=np.float64) ok = cnt > 0 out[ok] = s[ok] / cnt[ok] return out
[docs] def _nan_stderr_of_mean_axis0(stacked_sigma: np.ndarray, stacked_ccf: np.ndarray) -> np.ndarray: """ Standard error of ``nanmean(stacked_ccf, axis=0)`` when each row is an independent estimate with 1σ ``stacked_sigma[i, :]`` at each velocity. Uses :math:`\\sigma_{\\mu,j}=\\sqrt{\\sum_i \\sigma_{ij}^2}\\,/\\,n_j` where the sum and :math:`n_j` use the same rows as the column-wise mean (finite ``stacked_ccf``; only rows with finite nonnegative ``stacked_sigma`` contribute to the sum of variances). This matches the scale of the **mean** CCF; using ``sqrt(mean(σ²))`` instead would track a **typical single-row** σ and overstate uncertainty on the mean by ~ :math:`\\sqrt{n}` when rows are similar. """ sig = np.asarray(stacked_sigma, dtype=np.float64) ccf = np.asarray(stacked_ccf, dtype=np.float64) if sig.shape != ccf.shape: raise ValueError("_nan_stderr_of_mean_axis0: sigma and ccf stacks must have the same shape") if ccf.ndim != 2: raise ValueError("_nan_stderr_of_mean_axis0: expected 2-D arrays") n_row, n_col = ccf.shape if n_col == 0: return np.array([], dtype=np.float64) if n_row == 0: return np.full(n_col, np.nan, dtype=np.float64) fin_ccf = np.isfinite(ccf) cnt = np.sum(fin_ccf, axis=0, dtype=np.float64) use = fin_ccf & np.isfinite(sig) & (sig >= 0) sum_sq = np.sum(np.where(use, sig**2, 0.0), axis=0) out = np.full(n_col, np.nan, dtype=np.float64) ok = cnt > 0 out[ok] = np.sqrt(np.maximum(sum_sq[ok], 0.0)) / cnt[ok] return out
[docs] def _rv_err_slope_propagation_m_s( v_m_s: np.ndarray, y_ccf: np.ndarray, sigma_ccf: np.ndarray | None, ) -> float: """ Diagonal error propagation σ_RV ≈ σ_y / ``|d(CCF)/dv|`` (m/s), v in m/s. Uses a robust high-percentile of ``|dCCF/dv|`` in the central part of the window so a single noisy bin does not dominate. When ``sigma_ccf`` is missing, uses ``mad_std`` of ``y_ccf`` as a noise scale. The result is **not** clipped to an arbitrary upper bound; very large values indicate a near-flat CCF or tiny ``|dCCF/dv|``. """ v0 = np.asarray(v_m_s, np.float64).ravel() y0 = np.asarray(y_ccf, np.float64).ravel() if v0.size != y0.size or v0.size < 5: return float("nan") s0 = None if sigma_ccf is not None: s0 = np.asarray(sigma_ccf, np.float64).ravel() if s0.size != v0.size: s0 = None m = np.isfinite(v0) & np.isfinite(y0) if s0 is not None: m &= np.isfinite(s0) & (s0 > 0) v, y = v0[m], y0[m] se = s0[m] if s0 is not None else None if v.size < 5: m2 = np.isfinite(v0) & np.isfinite(y0) v, y = v0[m2], y0[m2] se = s0[m2] if s0 is not None else None if v.size < 5: return float("nan") o = np.argsort(v) v = v[o] y = y[o] if se is not None: se = se[o] if float(np.nanmax(v)) <= float(np.nanmin(v)): return float("nan") dye = np.gradient(y, v) abs_g = np.abs(dye) lo, hi = np.nanquantile(v, [0.15, 0.85]) cen = (v >= lo) & (v <= hi) if not np.any(cen): cen = np.ones_like(v, dtype=bool) g_use = abs_g[cen] g95 = float(np.nanpercentile(g_use, 95)) if g_use.size else float("nan") if not math.isfinite(g95) or g95 <= 0: g95 = float(np.nanmax(abs_g)) if not math.isfinite(g95) or g95 <= 0: return float("nan") if se is not None and np.any(np.isfinite(se) & (se > 0)): sig_y = float(np.nanmedian(se[np.isfinite(se) & (se > 0)])) else: sig_y = float(mad_std(y, ignore_nan=True)) if not math.isfinite(sig_y) or sig_y <= 0: return float("nan") est = sig_y / g95 if not math.isfinite(est) or est <= 0: return float("nan") return float(est)
[docs] def build_centered_uniform_velocity_grid( center_m_s: float, half_width_m_s: float, step_m_s: float, ) -> np.ndarray: """ Uniform CCF velocity samples on ``[center − half_width, center + half_width]``. Spacing is constant (``step_m_s``) across the whole window. """ vc = float(center_m_s) hw = float(half_width_m_s) vs = float(step_m_s) if not np.isfinite(vc) or not np.isfinite(hw) or hw <= 0: raise ValueError( "build_centered_uniform_velocity_grid: center and half-width must be " "finite and half-width > 0" ) if not np.isfinite(vs) or vs <= 0: raise ValueError( "build_centered_uniform_velocity_grid: step must be finite and > 0" ) v_lo = vc - hw v_hi = vc + hw if v_hi <= v_lo: raise ValueError("build_centered_uniform_velocity_grid: window is empty") return np.arange(v_lo, v_hi + 0.5 * vs, vs, dtype=np.float64)
# ============================================================================= # RVCCF tables and flattened chunk wavelength bounds (L2 RVCCF_FIB* columns) # =============================================================================
[docs] def build_rvccf_chunk_supplement( *, chunk_id: np.ndarray, n_good: np.ndarray, v_min: float, v_max: float, v_step: float, ccf_2d: np.ndarray, bis: np.ndarray | None = None, bis_err: np.ndarray | None = None, ) -> Table: """ Supplement table with raw CCF(v) per chunk (columns merged into ``RVCCF_FIB*``). Parameters ---------- ccf_2d : np.ndarray Shape ``(n_chunk, n_vel)``; row ``i`` is the CCF for chunk ``i``. bis, bis_err : np.ndarray or None Optional per-chunk Queloz BIS and uncertainty (m/s). When omitted, columns are filled with NaN. """ n = int(ccf_2d.shape[0]) if ccf_2d.ndim >= 2 else 0 if n == 0: return Table( names=[ "CHUNK_ID", "N_GOOD", "V_MIN", "V_MAX", "V_STEP", "N_VEL", "CCF", "BIS", "BIS_ERR", ], dtype=[ np.int32, np.int32, np.float64, np.float64, np.float64, np.int32, object, np.float64, np.float64, ], ) if len(chunk_id) != n or len(n_good) != n: raise ValueError("build_rvccf_chunk_supplement: chunk_id / n_good length mismatch vs ccf_2d") n_vel = int(ccf_2d.shape[1]) ccf_col = np.empty(n, dtype=object) for i in range(n): ccf_col[i] = np.asarray(ccf_2d[i], dtype=RVCCF_CCF_ELEM_DTYPE).ravel() v_min_f = float(v_min) v_max_f = float(v_max) v_step_f = float(v_step) if bis is None: bis_a = np.full(n, np.nan, dtype=np.float64) else: bis_a = np.asarray(bis, dtype=np.float64).ravel() if bis_a.size != n: raise ValueError("build_rvccf_chunk_supplement: bis length mismatch vs ccf_2d") if bis_err is None: bis_err_a = np.full(n, np.nan, dtype=np.float64) else: bis_err_a = np.asarray(bis_err, dtype=np.float64).ravel() if bis_err_a.size != n: raise ValueError("build_rvccf_chunk_supplement: bis_err length mismatch vs ccf_2d") return Table( { "CHUNK_ID": np.asarray(chunk_id, dtype=np.int32).ravel(), "N_GOOD": np.asarray(n_good, dtype=np.int32).ravel(), "V_MIN": np.full(n, v_min_f, dtype=np.float64), "V_MAX": np.full(n, v_max_f, dtype=np.float64), "V_STEP": np.full(n, v_step_f, dtype=np.float64), "N_VEL": np.full(n, n_vel, dtype=np.int32), "CCF": ccf_col, "BIS": bis_a, "BIS_ERR": bis_err_a, } )
[docs] def assemble_rvccf_fib_table( rvs: np.ndarray, rv_errs: np.ndarray, wavelengths: np.ndarray, orders: np.ndarray, inlier: np.ndarray, *, supplement: Table | None = None, ) -> Table: """ Full per-chunk ``RVCCF_FIB*`` table: RV metrics plus optional CCF supplement columns. When ``supplement`` is None or has length 0, ``CCF`` rows are empty arrays (``RVCCF_CCF_ELEM_DTYPE``), ``N_GOOD`` is -1, and velocity metadata is NaN / ``N_VEL`` 0. """ n = len(rvs) mbjd = np.zeros(n, dtype=np.float64) berv = np.zeros(n, dtype=np.float64) res = np.full(n, np.nan, dtype=np.float64) tell_abs = np.zeros(n, dtype=np.float64) bis = np.full(n, np.nan, dtype=np.float64) bis_err = np.full(n, np.nan, dtype=np.float64) rv_abs = np.zeros(n, dtype=np.float64) rv_abs_err = np.zeros(n, dtype=np.float64) order_col = np.asarray(orders, dtype=np.int64).ravel() if len(order_col) != n: order_col = np.full(n, -1, dtype=np.int64) order_i16 = np.clip(order_col, -32768, 32767).astype(np.int16) wl = np.asarray(wavelengths, dtype=np.float64) inlier_u8 = np.asarray(inlier, dtype=np.uint8) if supplement is None or len(supplement) == 0: chunk_id = np.arange(n, dtype=np.int32) n_good = np.full(n, -1, dtype=np.int32) v_min_a = np.full(n, np.nan, dtype=np.float64) v_max_a = np.full(n, np.nan, dtype=np.float64) v_step_a = np.full(n, np.nan, dtype=np.float64) n_vel = np.zeros(n, dtype=np.int32) ccf_col = np.empty(n, dtype=object) for i in range(n): ccf_col[i] = np.array([], dtype=RVCCF_CCF_ELEM_DTYPE) else: if len(supplement) != n: raise ValueError( f"assemble_rvccf_fib_table: supplement has {len(supplement)} rows, " f"expected {n} to match per-chunk RV arrays" ) chunk_id = np.asarray(supplement["CHUNK_ID"], dtype=np.int32) n_good = np.asarray(supplement["N_GOOD"], dtype=np.int32) v_min_a = np.asarray(supplement["V_MIN"], dtype=np.float64) v_max_a = np.asarray(supplement["V_MAX"], dtype=np.float64) v_step_a = np.asarray(supplement["V_STEP"], dtype=np.float64) n_vel = np.asarray(supplement["N_VEL"], dtype=np.int32) ccf_col = np.empty(n, dtype=object) for i in range(n): raw = supplement["CCF"][i] if raw is None or (isinstance(raw, np.ndarray) and raw.size == 0): ccf_col[i] = np.array([], dtype=RVCCF_CCF_ELEM_DTYPE) else: ccf_col[i] = np.asarray(raw, dtype=RVCCF_CCF_ELEM_DTYPE).ravel() if "BIS" in supplement.colnames: bis = np.asarray(supplement["BIS"], dtype=np.float64).ravel() if "BIS_ERR" in supplement.colnames: bis_err = np.asarray(supplement["BIS_ERR"], dtype=np.float64).ravel() return Table( { "MBJDW": mbjd, "BERVW": berv, "RV": np.asarray(rvs, dtype=np.float64), "RV_ERR": np.asarray(rv_errs, dtype=np.float64), "ORDER": order_i16, "WAVELENGTH": wl, "RESOLUTION": res, "TELL_ABS": tell_abs, "BIS": bis, "BIS_ERR": bis_err, "RV_ABS": rv_abs, "RV_ABS_ERR": rv_abs_err, "INLIER": inlier_u8, "CHUNK_ID": chunk_id, "N_GOOD": n_good, "V_MIN": v_min_a, "V_MAX": v_max_a, "V_STEP": v_step_a, "N_VEL": n_vel, "CCF": ccf_col, } )
[docs] def flat_chunk_wl_lo_hi( wave_2d: np.ndarray, order_indices: np.ndarray, n_chunks_per_order: np.ndarray, chunk_start: np.ndarray, total_chunks: int, ) -> tuple[np.ndarray, np.ndarray]: """ Wavelength bounds per flattened chunk index (matches Numba chunking in :func:`_process_all_orders_ccf_numba`). """ wl_lo = np.full(total_chunks, np.nan, dtype=np.float64) wl_hi = np.full(total_chunks, np.nan, dtype=np.float64) for j in range(len(order_indices)): oi = int(order_indices[j]) w = wave_2d[oi] w_min = float(np.nanmin(w)) w_max = float(np.nanmax(w)) n_chunks = int(n_chunks_per_order[j]) if n_chunks < 1 or not np.isfinite(w_min) or not np.isfinite(w_max) or w_max <= w_min: continue start = int(chunk_start[j]) for k in range(n_chunks): idx = start + k if idx >= total_chunks: break wl_lo[idx] = w_min + k * (w_max - w_min) / n_chunks wl_hi[idx] = w_min + (k + 1) * (w_max - w_min) / n_chunks return wl_lo, wl_hi
# ============================================================================= # Gaussian CCF fit (LM + σ heuristics; config in km/s, public API in m/s) # =============================================================================
[docs] def _gaussian_ccf_model(v: np.ndarray, amplitude: float, v0: float, sigma: float, baseline: float) -> np.ndarray: return amplitude * np.exp(-0.5 * ((v - v0) / np.maximum(sigma, 1e-10)) ** 2) + baseline
[docs] def clip_gaussian_plot_velocity_range_m_s( lo_m_s: float, hi_m_s: float, *, v_grid_min_m_s: float | None = None, v_grid_max_m_s: float | None = None, v_samples_m_s: np.ndarray | None = None, ) -> tuple[float, float]: """ Bound ``[lo_m_s, hi_m_s]`` for evaluating a Gaussian CCF model. The returned interval is the intersection of ``[lo_m_s, hi_m_s]`` with the span of the CCF velocity axis (``v_grid_*`` or ``v_samples_m_s``), further clipped to the module absolute limits ``V_MIN_DEFAULT_M_S`` … ``V_MAX_DEFAULT_M_S`` (m/s), matching the broad CCF grid used in :func:`resolve_ccf_broad_grid_m_s` and related paths. """ if v_grid_min_m_s is None or v_grid_max_m_s is None: if v_samples_m_s is not None and np.size(v_samples_m_s) > 0: va = np.asarray(v_samples_m_s, dtype=np.float64).ravel() gmin = float(np.nanmin(va)) gmax = float(np.nanmax(va)) else: gmin, gmax = float(V_MIN_DEFAULT_M_S), float(V_MAX_DEFAULT_M_S) else: gmin = float(v_grid_min_m_s) gmax = float(v_grid_max_m_s) gmin = max(gmin, float(V_MIN_DEFAULT_M_S)) gmax = min(gmax, float(V_MAX_DEFAULT_M_S)) lo = max(float(lo_m_s), gmin) hi = min(float(hi_m_s), gmax) if not (math.isfinite(lo) and math.isfinite(hi)) or lo >= hi: lo, hi = gmin, gmax return lo, hi
[docs] def estimate_ccf_uncertainty_highpass_residual( ccf: np.ndarray, *, lowpass_window: int = 51, savgol_polyorder: int = 3, ) -> tuple[float, np.ndarray, np.ndarray]: """ Estimate a **single** CCF uncertainty σ (same units as ``ccf``): Savitzky–Golay low-pass smooth, subtract to form a high-frequency residual, then take the RMS of successive differences in that residual (pixel-to-pixel scale). **Line-mask CCF path** (:func:`run_ccf_line_mask_for_fiber`; ``ccf_line_mask`` primitive): this is the primary model for ``ccf_err`` on the per-order mean CCF (uniform array filled with ``sigma``), and for the stacked rows passed into :func:`finalize_ccf_preview_dict` (replacing the former per-chunk weighted SD + stderr-of-mean combination). Parameters ---------- ccf : ndarray CCF samples (same shape as used for Gaussian fitting). lowpass_window : int Savitzky–Golay window length (forced odd); capped to array length. Larger ⇒ stronger low-pass (more large-scale structure removed from the residual). savgol_polyorder : int Savitzky–Golay polynomial order (must be ``< window_length``). Returns ------- sigma : float Scalar σ applied uniformly at each velocity bin when building ``ccf_err`` for :func:`fit_ccf_rv`. ccf_lowpass : ndarray Low-pass (smooth) component of ``ccf``. residual : ndarray ``ccf - ccf_lowpass`` (high-pass remainder). """ y = np.asarray(ccf, dtype=np.float64).ravel() if np.any(~np.isfinite(y)): m = np.isfinite(y) med = float(np.nanmedian(y[m])) if np.any(m) else 0.0 if not np.isfinite(med): med = 0.0 y = np.where(np.isfinite(y), y, med) n = int(y.size) if n < 3: z = np.zeros_like(y) return float("nan"), np.asarray(y, dtype=np.float64), z wl = int(lowpass_window) if wl % 2 == 0: wl += 1 wl = max(5, wl) if wl > n: wl = n if n % 2 == 1 else n - 1 wl = max(5, wl) po = int(savgol_polyorder) po = max(1, min(po, wl - 1)) try: smooth = savgol_filter(y, wl, po, mode="interp") except Exception: size = max(3, min(wl, n if n % 2 == 1 else n - 1)) if size % 2 == 0: size -= 1 size = max(3, size) smooth = uniform_filter1d(y, size=size, mode="nearest") res = y - smooth dd = np.diff(res) sigma = float(np.sqrt(np.nanmean(dd * dd))) if not math.isfinite(sigma) or sigma <= 0.0: sigma = float(np.nanstd(res)) if not math.isfinite(sigma) or sigma <= 0.0: sigma = max(float(np.nanstd(y)), 1e-30) return sigma, smooth, res
[docs] @dataclass class CCFFitConfig: """ Tunables for :func:`fit_ccf_rv` two-pass Gaussian + constant fits to :math:`\\mathrm{CCF}(v)`. Velocity windows in the first and second pass are expressed in **km s\\ :sup:`−1`** (``*_km_s`` fields); RV results from :func:`fit_ccf_rv` are still returned in **m s\\ :sup:`−1`**. """ # Wider windows help the LM Gaussian recover a sensible baseline away from the peak. pass1_half_width_km_s: float = 800.0 pass2_half_width_km_s: float = 120.0 initial_stddev_km_s: float = 5.0 min_points: int = 5 emission_strength_ratio: float = 1.02 cal_mask_methods: frozenset = frozenset({"thar", "lfc", "etalon"}) # Levenberg–Marquardt iterations per Gaussian fit (χ² with optional inverse-variance weights). levmar_maxiter: int = 1500 # Unclipped prefit passes on the **full** velocity window (no point removal): repeated # LM fits to drive χ² down before any sigma-clipping refinement. sigma_clip_unclipped_prefit_passes: int = 2 # After prefit, this many iterations: fit → clip outliers → refit (each pass uses LM). sigma_clip_enable: bool = True sigma_clip_max_iter: int = 10 # MAD multiplier for residual clipping after prefit (tighter than relaxed). sigma_clip_n_sigma: float = 4.0 # Weaker clipping for the first few post-prefit rounds (keep more points while refining). sigma_clip_n_sigma_relaxed: float = 6.0 sigma_clip_relax_first_clip_iters: int = 3 sigma_clip_min_keep_frac: float = 0.30 # How to merge gradient-based CCF error with LevMar covariance when both pass plausibility. # ``"max"`` is more conservative than historic ``"min"`` (often gave tiny σ_RV). rv_err_cov_combine: str = "max" # Parametric bootstrap: refit Gaussian on CCF + N(0, σ_ccf) noise (same window/weights as # the final pass). 0 disables. Typical 24–64 for science; each sample is one LM fit. rv_err_bootstrap_samples: int = 0 rv_err_bootstrap_seed: int | None = None
# Lighter LevMar / σ-clip budget for :func:`finalize_ccf_preview_dict` only (Plotly metadata). # Pipeline RV fits on order-mean CCFs keep the default :class:`CCFFitConfig`. CCF_PREVIEW_SLOT_FIT_CONFIG = CCFFitConfig( levmar_maxiter=450, sigma_clip_unclipped_prefit_passes=1, sigma_clip_max_iter=6, )
[docs] def _line_mask_ccf_fit_free_baseline_requested( *, fit_ccf_baseline_free: bool | None, line_mask_line_window_by_line: bool | None, ccf_line_mask_stored_negated: bool | None = None, ) -> bool: """ True when :func:`fit_ccf_rv` should treat the CCF constant term as an LM parameter. For line-mask **line-by-line** chunking (``window_line_by_line``), the velocity span is often only a few km s\\ :sup:`−1` wide, so a robust median baseline estimated from essentially the entire profile is a poor substitute for wings; fitting ``Const1D`` jointly with the Gaussian avoids that bias. For ``ccf_line_mask_stored_negated=True`` (line-mask / ``ccf_line_mask`` stored CCF rows), the baseline is **not** a free LM parameter: a free ``Gaussian1D + Const1D`` is χ²-degenerate (Gaussian amplitude collapses toward zero and the line is absorbed by the constant), which breaks Plotly Gaussian overlays. Pass half-width caps still apply when ``ccf_line_mask_stored_negated`` is true (see :func:`fit_ccf_rv`), so fixed sigma-clipped baselines remain local to the fit window. """ if fit_ccf_baseline_free is not None: return bool(fit_ccf_baseline_free) if not bool(line_mask_line_window_by_line): return False if bool(ccf_line_mask_stored_negated): return False return True
[docs] def _bootstrap_gaussian_rv_std_m_s( gx_km: np.ndarray, gy0: np.ndarray, ge: np.ndarray, *, seed_mean_km: float, seed_std_km: float, profile: str, n_samples: int, rng: np.random.Generator, maxiter: int = 400, free_baseline: bool = False, ccf_line_mask_stored_negated: bool | None = None, ) -> float: """ Scatter of the fitted Gaussian mean (m/s) when each CCF sample is perturbed by its reported σ (i.i.d.); ignores bin-to-bin correlation. Uses weighted LM like the main fit. """ if n_samples < 4 or gy0.size < 5: return float("nan") gx = np.asarray(gx_km, np.float64).ravel() y0 = np.asarray(gy0, np.float64).ravel() gerr = np.asarray(ge, np.float64).ravel() if gx.size != y0.size or gerr.size != y0.size: return float("nan") good = np.isfinite(gx) & np.isfinite(y0) & np.isfinite(gerr) & (gerr > 0) if int(np.count_nonzero(good)) < 5: return float("nan") gx = gx[good] y0 = y0[good] gerr = gerr[good] w = 1.0 / (gerr * gerr) ft = fitting.LevMarLSQFitter() means = np.empty(n_samples, dtype=np.float64) for i in range(n_samples): yn = y0 + rng.standard_normal(y0.shape) * gerr ys = _levmar_ccf_y_scale(yn) yn_s = np.asarray(yn, dtype=np.float64) * ys if free_baseline: bg_raw = float(np.nanmedian(np.asarray(yn, dtype=np.float64))) if not np.isfinite(bg_raw): bg_raw = 0.0 else: bg_raw = _ccf_background_sigma_clipped_median(np.asarray(yn, dtype=np.float64)) if not np.isfinite(bg_raw): bg_raw = float(np.median(yn)) bmed = float(bg_raw * ys) gy = yn_s - bmed span = abs(float(np.nanmax(gy) - np.nanmin(gy))) * 100.0 amp = ( max(-1e7, float(np.nanmin(gy)) - span) if profile == "emission" else min(1e7, float(np.nanmax(gy)) + span) ) if bool(ccf_line_mask_stored_negated): amp = max(float(amp), 1e-30) amp_floor_s = 0.0 if free_baseline and (bool(ccf_line_mask_stored_negated) or profile == "absorption"): amp_floor_s = _ccf_gaussian_amp_floor_free_baseline_scaled(gy, ys) amp = max(float(amp), 2.0 * amp_floor_s) try: init_b = Gaussian1D( amplitude=amp, mean=float(seed_mean_km), stddev=float(seed_std_km) ) + Const1D(amplitude=bmed) if free_baseline and (bool(ccf_line_mask_stored_negated) or profile == "absorption"): init_b.amplitude_0.min = float(amp_floor_s) elif bool(ccf_line_mask_stored_negated): init_b.amplitude_0.min = 0.0 if not free_baseline: init_b.amplitude_1.fixed = True w_eff = np.asarray(w, dtype=np.float64) / (ys * ys) gfit = _levmar_lsq_fit(ft, init_b, gx, yn_s, weights=w_eff, maxiter=maxiter) means[i] = float(gfit.mean_0.value) * 1000.0 except Exception: means[i] = float("nan") fin = np.isfinite(means) if int(np.count_nonzero(fin)) < max(4, n_samples // 4): return float("nan") mv = means[fin] return float(np.std(mv, ddof=1))
[docs] def dv_per_pixel_m_s(wl_um: float) -> float: """ Rough echelle resolving element per detector pixel in velocity units (m/s). Uses the HISPEC-style mapping ``order ≈ 147 / λ (µm)`` and ``n_pix = 4096`` so ``Δv ≈ c / (order · n_pix)``. This is a **diagnostic** scale for CCF sampling and error heuristics, not a physical FWHM. With :math:`\\Delta v = c\\,(\\Delta\\lambda/\\lambda)`, center wavelength :math:`\\lambda \\approx 147/\\,{\\rm order}` µm, and pixel width :math:`\\Delta\\lambda \\approx (147/{\\rm order}^2)/4096` µm, this gives :math:`\\Delta v = c / ({\\rm order}\\cdot4096)` m/s. Typical L2 scales: BSPEC (orders ~110–148) ~494–665 m/s per pixel; RSPEC (orders ~60–97) ~755–1220 m/s per pixel. Parameters ---------- wl_um : float Wavelength in micron (positive, finite). Returns ------- float Δv per pixel (m/s), or NaN if ``wl_um`` is non-finite or non-positive. """ if not np.isfinite(wl_um) or wl_um <= 0: return float("nan") return float(C_M_S / (max(147.0 / wl_um, 1.0) * 4096.0))
[docs] def median_pixel_dv_m_s(wave_um: np.ndarray) -> float: """Median detector-pixel velocity width (m/s) from a 1-D wavelength row.""" w = np.asarray(wave_um, dtype=np.float64).ravel() m = np.isfinite(w) & (w > 0.0) if int(np.count_nonzero(m)) < 2: return float("nan") ww = w[m] dw = float(np.median(np.abs(np.diff(ww)))) w0 = float(np.median(ww)) if not (dw > 0.0 and w0 > 0.0 and math.isfinite(dw) and math.isfinite(w0)): return float("nan") return float(C_M_S * dw / w0)
[docs] def _subsample_velocity_ccf_for_gaussian_fit( vm: np.ndarray, y: np.ndarray, y_err_ok: np.ndarray | None, v_step_m_s: float, max_samples: int, ) -> tuple[np.ndarray, np.ndarray, np.ndarray | None, float, int]: """ Uniform stride subsample along velocity when the grid is very long (line-mask broad scans). Preserves ordering; scales ``v_step_m_s`` by the stride so error heuristics stay consistent with the effective sample spacing. """ n = int(vm.size) ms = int(max_samples) if n <= ms or ms < 8: return vm, y, y_err_ok, float(v_step_m_s), 1 stride = int(math.ceil(n / float(ms))) stride = max(1, stride) vm_s = np.asarray(vm[::stride], dtype=np.float64) y_s = np.asarray(y[::stride], dtype=np.float64) err_s = ( np.asarray(y_err_ok[::stride], dtype=np.float64) if y_err_ok is not None and y_err_ok.size == n else None ) vstep_s = float(v_step_m_s) * float(stride) return vm_s, y_s, err_s, vstep_s, stride
[docs] def _ccf_fit_debug_jsonable(v): """Reduce fit_ccf_rv debug context values to JSON-friendly types.""" if isinstance(v, (bool, str, type(None))): return v if isinstance(v, (int, np.integer)): return int(v) if isinstance(v, (float, np.floating)): xf = float(v) return xf if np.isfinite(xf) else None if isinstance(v, dict): return {str(k): _ccf_fit_debug_jsonable(x) for k, x in v.items()} if isinstance(v, (list, tuple)): return [_ccf_fit_debug_jsonable(x) for x in v] return str(v)
[docs] def _levmar_lsq_fit(ft, init, *args, **kwargs): """ Run :class:`~astropy.modeling.fitting.LevMarLSQFitter`. Ill-conditioned fits can make ``scipy.optimize.leastsq`` overflow when forming ``cov_x``; downstream code already rejects non-physical covariances via ``_lm``. """ with warnings.catch_warnings(): warnings.simplefilter("ignore", RuntimeWarning) return ft(init, *args, **kwargs)
[docs] def _levmar_ccf_y_scale(gy: np.ndarray) -> float: """ Multiplicative scale so ``gy * scale`` has max absolute value ≈ 1. ``scipy.optimize.leastsq`` (used by Astropy :class:`~astropy.modeling.fitting.LevMarLSQFitter`) reports ``ierr`` outside {1,…,4} when the problem is poorly scaled (common for mask-CCF amplitudes ~1e-18), which triggers ``AstropyUserWarning: The fit may be unsuccessful``. Scaling **y** (and inverse-variance weights consistently) preserves Gaussian **mean** and **stddev** in velocity while improving conditioning. """ m = float(np.nanmax(np.abs(np.asarray(gy, dtype=np.float64)))) if not math.isfinite(m) or m <= 0: return 1.0 return 1.0 / m
[docs] def _ccf_gaussian_amp_floor_free_baseline_scaled( gy_det: np.ndarray, ys: float, *, frac_of_span: float = 0.005, frac_of_peak: float = 0.05, abs_scaled_floor: float = 0.0, ) -> float: """ Positive lower bound on Gaussian amplitude (LevMar **scaled** ``gy`` units) when the compound model is ``Gaussian1D + Const1D`` with **free** ``Const1D``: otherwise the fitter can drive Gaussian amplitude to **exactly zero** and absorb the line in the constant (χ² degeneracy), yielding flat preview Gaussians. Uses both a fraction of the detrended peak-to-valley span and a fraction of the **positive peak** above the median-detrended baseline: span alone can be noise-dominated on narrow mask-CCF grids, leaving a tiny floor that still allows an effectively flat Gaussian. Optional ``abs_scaled_floor`` (same units as scaled ``gy``) forces a minimum when peak-derived floors would otherwise be numerically negligible. """ contr = float(np.nanmax(gy_det) - np.nanmin(gy_det)) if not math.isfinite(contr): contr = 0.0 contr = max(0.0, contr) span_floor = max(1e-30 * float(ys), float(frac_of_span) * contr) pk = float(np.nanmax(gy_det)) if not math.isfinite(pk): pk = 0.0 peak_floor = max(0.0, float(frac_of_peak) * max(0.0, pk)) return max(span_floor, peak_floor, float(abs_scaled_floor))
[docs] def _gaussian_preview_params_from_peak_up_ccf( v_grid_m_s: np.ndarray, ccf_peak_up: np.ndarray, rv_m_s: float, rv_err_m_s: float, *, fit_ok: bool, config: CCFFitConfig | None = None, gaussian_seed_mean_m_s: float | None = None, ) -> tuple[dict, dict]: """ Build ``params`` / ``diagnostics`` for mask-line preview overlays when RV comes from :func:`~hispecdrp.primitives.utils.ccf.ccf_gauss_fit_numba.fit_ccf_rv_rows_numba`. """ cfg = config or CCFFitConfig() vg = np.asarray(v_grid_m_s, dtype=np.float64).ravel() y = np.asarray(ccf_peak_up, dtype=np.float64).ravel() v0 = float(rv_m_s) sig = float(cfg.initial_stddev_km_s) * 1000.0 amp = float("nan") base = float("nan") if fit_ok and np.isfinite(v0): half = max(2500.0, 2.5 * sig) loc = np.isfinite(vg) & np.isfinite(y) & (vg >= v0 - half) & (vg <= v0 + half) if int(np.count_nonzero(loc)) < 5: loc = np.isfinite(vg) & np.isfinite(y) if int(np.count_nonzero(loc)) >= 3: vl = vg[loc] yl = y[loc] peak = float(np.nanmax(yl)) mn = float(np.nanmin(yl)) if peak > mn: mid = mn + 0.5 * (peak - mn) above = vl[yl >= mid] if above.size >= 2: fwhm = float(np.nanmax(above) - np.nanmin(above)) if fwhm > 0.0: sig = max(sig, fwhm / 2.355) sig = max(float(sig), 1.0) g = np.exp(-0.5 * ((vl - v0) / sig) ** 2) mat = np.column_stack((g, np.ones(vl.size, dtype=np.float64))) coeff, _res, rank, _s = np.linalg.lstsq(mat, yl, rcond=None) if int(rank) >= 2 and np.all(np.isfinite(coeff)): amp = float(coeff[0]) base = float(coeff[1]) else: base = float(np.nanmedian(yl)) amp = max(peak - base, 0.0) if not np.isfinite(amp): amp = 0.0 if not np.isfinite(base): base = float(np.nanmedian(y[np.isfinite(y)])) if np.any(np.isfinite(y)) else 0.0 params = { "amplitude": float(amp), "v0": v0, "sigma": float(sig), "baseline": float(base), } diag: dict = { "fit_ok": bool(fit_ok and np.isfinite(v0) and np.isfinite(rv_err_m_s)), "ccf_line_mask_forced_peak_up_profile": True, "ccf_line_mask_stored_negated": True, "fit_via_numba_line_mask": True, "lm_gaussian_width_plausible": bool(fit_ok and sig > 0.0), "used_covariance_for_error": False, "used_sigma_fallback": False, "used_gradient_ccf_error": False, "used_ccf_pointwise_error": False, "profile": "absorption", "ccf_dir_style": "up", "message": "mask-line stored CCF via fit_ccf_rv_rows_numba", } if gaussian_seed_mean_m_s is not None and math.isfinite(float(gaussian_seed_mean_m_s)): diag["gaussian_seed_mean_m_s"] = float(gaussian_seed_mean_m_s) return params, diag
[docs] def _fit_ccf_rv_line_mask_stored_negated_via_numba( v_grid_m_s: np.ndarray, ccf: np.ndarray, v_step_m_s: float, n_good: int | None, *, return_params: bool, ccf_err: np.ndarray | None, config: CCFFitConfig | None, gaussian_seed_mean_m_s: float | None, ) -> tuple: """Mask-line stored CCF rows: use the same Numba centroid as the RVCCF pipeline.""" cfg = config or CCFFitConfig() vg = np.asarray(v_grid_m_s, dtype=np.float64).ravel() y0 = np.asarray(ccf, dtype=np.float64).ravel() ok_mask = np.isfinite(vg) & np.isfinite(y0) if int(np.sum(ok_mask)) < int(cfg.min_points): nan_pair = (np.nan, np.nan) if return_params: return nan_pair + ({}, {"fit_ok": False, "message": "insufficient valid points"}) return nan_pair err_row: np.ndarray | None = None if ccf_err is not None: er0 = np.asarray(ccf_err, dtype=np.float64).ravel() if er0.size == vg.size and np.any(np.isfinite(er0) & (er0 > 0)): err_row = er0.reshape(1, -1) rv_arr, err_arr, ok_arr = fit_ccf_rv_rows_numba( vg, y0.reshape(1, -1), ccf_err_rows=err_row, gaussian_seed_mean_m_s=gaussian_seed_mean_m_s, pass1_half_width_m_s=float(cfg.pass1_half_width_km_s) * 1000.0, pass2_half_width_m_s=float(cfg.pass2_half_width_km_s) * 1000.0, initial_stddev_m_s=float(cfg.initial_stddev_km_s) * 1000.0, levmar_maxiter=int(cfg.levmar_maxiter), min_points=int(cfg.min_points), max_cores=1, ) fit_ok = int(ok_arr[0]) == 1 rv_ms = float(rv_arr[0]) if fit_ok else float("nan") rv_err_ms = float(err_arr[0]) if fit_ok else float("nan") if not return_params: return rv_ms, rv_err_ms params, diag = _gaussian_preview_params_from_peak_up_ccf( vg, y0, rv_ms, rv_err_ms, fit_ok=fit_ok, config=cfg, gaussian_seed_mean_m_s=gaussian_seed_mean_m_s, ) return rv_ms, rv_err_ms, params, diag
[docs] def fit_ccf_rv( v_grid_m_s: np.ndarray, ccf: np.ndarray, v_step_m_s: float, n_good: int | None = None, return_params: bool = False, *, ccf_err: np.ndarray | None = None, mask_method: str | None = None, config: CCFFitConfig | None = None, vel_span_m_s_per_pixel: float | None = None, two_pass: bool = True, max_velocity_samples: int | None = 8192, ccf_line_mask_stored_negated: bool | None = None, fit_ccf_baseline_free: bool | None = None, line_mask_line_window_by_line: bool | None = None, gaussian_seed_mean_m_s: float | None = None, ): """ Fit a Gaussian plus constant baseline to a precomputed CCF and return RV ± error in m s⁻¹. Uses a robust emission/absorption profile guess, :class:`~astropy.modeling.models.Gaussian1D` plus :class:`~astropy.modeling.models.Const1D` on the CCF in a sliding velocity window (values are scaled to ~unit magnitude before LM; RV parameters are unchanged). By default the constant baseline is **fixed** to :func:`_ccf_background_sigma_clipped_median` of the CCF samples in each fit window (not a free LM parameter). When ``fit_ccf_baseline_free=True``, or when ``line_mask_line_window_by_line`` is true (narrow line-mask line-by-line grids) **and** ``ccf_line_mask_stored_negated`` is not true, the baseline is a **free** :class:`~astropy.modeling.models.Const1D` term fit jointly with the Gaussian, and pass half-widths are capped to a fraction of the available velocity span so the fit is not dominated by an artificial “global median” baseline across the whole short profile. The same half-width caps apply when ``ccf_line_mask_stored_negated`` is true (mask-line CCF), so fixed-baseline fits on short grids do not inherit multi-hundred-km pass windows. One or two Levenberg–Marquardt passes each use a **wide** velocity window (see :class:`CCFFitConfig`) to stabilize the Gaussian **amplitude** and width. Within each window the fitter runs **unclipped** χ² passes on the full sample (repeated LM with ``levmar_maxiter``), then **sigma-clipping** refinement with relaxed thresholds on the first clipping rounds. Formal uncertainty may use a KPF-inspired ``ccf_error`` scaling when plausible, else covariance from the fitter, else a σ/√n fallback. Parameters ---------- v_grid_m_s : np.ndarray Velocity samples (m s⁻¹), usually sorted (uniform broad or centered window). ccf : np.ndarray CCF values on the same grid. v_step_m_s : float Effective **finest** velocity spacing (m s⁻¹) for plausibility checks and ``n_sp`` scaling — typically :func:`effective_ccf_v_step_for_fit` on ``v_grid_m_s``. n_good : int or None, optional Number of good spectral pixels in the chunk (for fallback error scaling). return_params : bool, optional If True, return ``(rv, rv_err, params_dict, diag_dict)``; else ``(rv, rv_err)``. mask_method : str or None, optional If in ``CCFFitConfig.cal_mask_methods``, use absorption-style calibration peak logic. config : CCFFitConfig or None, optional Override fit windows and thresholds. vel_span_m_s_per_pixel : float or None, optional Spectral sampling scale passed into error heuristics. two_pass : bool, optional If True (default), run a second fit narrowed around the first mean. max_velocity_samples : int or None, optional When the input grid has more than this many finite samples, apply uniform stride subsampling for the Gaussian fit only (default ``8192``). Set ``None`` to always use the full grid. Does not change stored CCF arrays elsewhere — only speeds LM fitting on very long line-mask broad scans. ccf_err : np.ndarray or None, optional Per-sample CCF uncertainty (same shape as ``ccf``). When finite and predominantly positive, Levenberg–Marquardt fits use ``weights = 1/ccf_err²`` on the raw CCF samples in each pass window. ccf_line_mask_stored_negated : bool or None, optional When not ``None``, recorded in the diagnostics dict (when ``return_params`` is True) as ``"ccf_line_mask_stored_negated"``. Use ``True`` for mask-line CCF rows produced by :func:`rv_per_chunks_line_mask` / :func:`run_ccf_line_mask_for_fiber` (stored convention: negated from the raw weighted mask statistic so the peak is near the true RV). When ``True``, the fitter **does not** use the data-driven emission/absorption heuristic: it assumes a **peak-up** line (positive :class:`~astropy.modeling.models.Gaussian1D` amplitude in scaled units, seed at the discrete maximum) and sets ``Gaussian1D.amplitude`` lower bound to ``0`` so LM cannot flip to a spurious negative-lobe solution on flat mask CCFs. ``None`` (default) omits the key — caller convention unknown. fit_ccf_baseline_free : bool or None, optional When ``True``, fit the CCF constant baseline in LM (do not fix ``Const1D``). When ``None`` (default), use :func:`_line_mask_ccf_fit_free_baseline_requested` with ``line_mask_line_window_by_line`` to decide. line_mask_line_window_by_line : bool or None, optional Line-mask line-by-line chunking flag (same meaning as ``window_line_by_line`` on the primitive). When ``fit_ccf_baseline_free`` is ``None`` and this is true, free-baseline mode is enabled automatically unless ``ccf_line_mask_stored_negated`` is true (see :func:`_line_mask_ccf_fit_free_baseline_requested`). gaussian_seed_mean_m_s : float or None, optional When ``ccf_line_mask_stored_negated`` is true and this lies on the velocity grid, the discrete peak seed uses **argmax(CCF)** restricted to samples within a local window around this value (typically ``ccf_input_velocity``), instead of the global maximum on the full grid. That avoids spurious seeds on stacked mean CCFs and aligns pass-1 with the injected search center. Returns ------- tuple If ``return_params`` is False: ``(rv_ms, rv_err_ms)``. If True: ``(rv_ms, rv_err_ms, params, diag)`` with fitted Gaussian parameters and diagnostic metadata. Notes ----- Design parallels public KPF PRV CCF-fitting ideas; see module ``References``. When both the gradient-based CCF error and the Levenberg–Marquardt covariance on the Gaussian mean pass plausibility checks, :class:`CCFFitConfig` field ``rv_err_cov_combine`` chooses **``min``** (historic) or **``max``** (more conservative; default). Optional **parametric bootstrap** (``rv_err_bootstrap_samples`` > 0): repeatedly add i.i.d. ``N(0, ccf_err)`` noise to the final-window CCF samples, refit the weighted Gaussian, and take the sample standard deviation of fitted means (m/s). The reported ``rv_err`` is **at least** that bootstrap scatter when bootstrap runs (still diagonal / uncorrelated noise; see Notes). **Self-consistency of ``ccf_err`` → ``rv_err`` (what is *not* done).** - ``ccf_err`` is used only as **diagonal** inverse-variance weights ``1/σ²`` on the **raw** CCF samples inside each fit window (Gaussian + constant model). For the line-mask primitive (``ccf_line_mask``), those σ come from the weighted SD of per-line :math:`F\\,\\mathrm{SN}` about the chunk CCF, then combined across chunks as a standard error of the mean; this is not a full propagation from pixel flux errors, and **bin-to-bin correlations** in :math:`v` are ignored. - The Levenberg–Marquardt **covariance** on the Gaussian mean (when returned by Astropy) is a **local** linearization error for the weighted nonlinear fit; it does not add systematic terms from model mismatch (true line profile ≠ Gaussian). - The **gradient-based** ``_gradient_ccf_err_km`` branch uses gradients of the **raw** CCF (``√|CCF|`` scaling) and **does not** use ``ccf_err``. It returns **0** if any CCF sample in the fit window is **negative**, so for strongly absorption-shaped curves the gradient branch may be inactive and ``rv_err`` relies on covariance or fallbacks. With ``rv_err_cov_combine="min"``, **``min(gradient, cov)``** can still yield an **optimistically small** ``rv_err``; default ``"max"`` is more conservative. - If the LM Gaussian **width** collapses toward zero, the formal covariance on the mean can reach ~1e-16 m/s while still passing ``_ok_err``; such fits set ``diag["lm_gaussian_width_plausible"]=False``, drop the covariance branch, and combine ``rv_err`` with :func:`_rv_err_slope_propagation_m_s` (CCF + ``ccf_err``) and a widened ``σ/√n`` fallback using ``v_step``. - When the LevMar **covariance** is used for ``rv_err``, slope propagation is still computed for ``diag["rv_err_slope_propagation_m_s"]`` but is **not** forced as a minimum on ``rv_err`` (no 200 km/s-style floor from ``max(rv_err, σ_slope)``). """ cfg = config or CCFFitConfig() if bool(ccf_line_mask_stored_negated): return _fit_ccf_rv_line_mask_stored_negated_via_numba( v_grid_m_s, ccf, v_step_m_s, n_good, return_params=return_params, ccf_err=ccf_err, config=cfg, gaussian_seed_mean_m_s=gaussian_seed_mean_m_s, ) free_bl = _line_mask_ccf_fit_free_baseline_requested( fit_ccf_baseline_free=fit_ccf_baseline_free, line_mask_line_window_by_line=line_mask_line_window_by_line, ccf_line_mask_stored_negated=ccf_line_mask_stored_negated, ) _ccf_line_mask_diag: dict[str, bool] = {} if ccf_line_mask_stored_negated is not None: _ccf_line_mask_diag["ccf_line_mask_stored_negated"] = bool(ccf_line_mask_stored_negated) def _fail(msg: str, **ctx): d = { "fit_ok": False, "used_covariance_for_error": False, "used_sigma_fallback": False, "used_gradient_ccf_error": False, "used_ccf_pointwise_error": False, "sigma_clip_enabled": bool(cfg.sigma_clip_enable), "sigma_clip_iterations": 0, "sigma_clip_n_points_initial": 0, "sigma_clip_n_points_final": 0, "rv_err_bootstrap_sigma_m_s": float("nan"), "used_rv_err_bootstrap": False, "rv_err_cov_combine": str(cfg.rv_err_cov_combine), "applied_slope_propagation_floor": False, "message": msg, } if ctx: dbg = {k: _ccf_fit_debug_jsonable(v) for k, v in ctx.items()} d["debug_context"] = dbg try: extra = json.dumps(dbg, sort_keys=True) except (TypeError, ValueError): extra = str(dbg) logger.warning("CCF fit: %s | %s", msg, extra) else: logger.warning("CCF fit: %s", msg) d.update(_ccf_line_mask_diag) return (np.nan, np.nan, {}, d) if return_params else (np.nan, np.nan) vg = np.asarray(v_grid_m_s, np.float64).ravel() y0 = np.asarray(ccf, np.float64).ravel() ok = np.isfinite(vg) & np.isfinite(y0) n_ok_pre = int(np.sum(ok)) if n_ok_pre < cfg.min_points + 2: return _fail( "insufficient valid points", fit_stage="input_grid", reason="Too few finite (velocity, CCF) pairs after masking non-finite values", n_finite_pairs=n_ok_pre, min_pairs_required=int(cfg.min_points + 2), min_points_fit_config=int(cfg.min_points), raw_grid_size=int(vg.size), ) vm, y = vg[ok], y0[ok] y_err_ok: np.ndarray | None = None if ccf_err is not None: er0 = np.asarray(ccf_err, np.float64).ravel() if er0.size == vg.size: y_err_ok = er0[ok] v_step_fit = float(v_step_m_s) subsample_stride = 1 if max_velocity_samples is not None and int(max_velocity_samples) > 0: vm, y, y_err_ok, v_step_fit, subsample_stride = _subsample_velocity_ccf_for_gaussian_fit( vm, y, y_err_ok, v_step_fit, int(max_velocity_samples) ) vk = vm / 1000.0 mm = str(mask_method).lower() if mask_method else "" forced_line_mask_peak_up = False if mm in cfg.cal_mask_methods: profile, seed_ms = "absorption", float(vm[int(np.nanargmax(y))]) elif bool(ccf_line_mask_stored_negated): # Mask-line CCF rows use :data:`LINE_MASK_CCF_STORED_NEGATED_FROM_RAW`: the physical line # sits at a **maximum** on the stored grid. The generic emission/absorption heuristic # mislabels nearly-flat weighted mask CCFs and flips the Gaussian sign, so LM chases the # wrong extremum. Fix profile to the code path that uses a **positive** Gaussian # amplitude and seeds at the discrete maximum (same convention as cal-mask absorption). profile = "absorption" forced_line_mask_peak_up = True v_lo, v_hi = float(np.min(vm)), float(np.max(vm)) v_span = float(v_hi - v_lo) if vm.size > 1 else 0.0 g_seed = gaussian_seed_mean_m_s if ( g_seed is not None and math.isfinite(float(g_seed)) and v_lo <= float(g_seed) <= v_hi and v_span > 0.0 ): g0 = float(g_seed) # Wide enough around the injected / scout RV, narrow enough to reject a higher # spurious extremum on the opposite end of a short window. half_w = max(3500.0, 0.38 * v_span) msk = (vm >= g0 - half_w) & (vm <= g0 + half_w) if int(np.count_nonzero(msk)) >= int(cfg.min_points): yy, vv = y[msk], vm[msk] seed_ms = float(vv[int(np.nanargmax(yy))]) else: seed_ms = float(vm[int(np.nanargmax(y))]) else: seed_ms = float(vm[int(np.nanargmax(y))]) else: med = float(np.median(y)) imx, imn = int(np.nanargmax(y)), int(np.nanargmin(y)) profile = ( "emission" if (med - y[imn]) > cfg.emission_strength_ratio * max(y[imx] - med, 1e-30) else "absorption" ) seed_ms = float(vm[imn if profile == "emission" else imx]) rv_gk = seed_ms / 1000.0 # Use caller's effective step (recomputing mean spacing here biased gradient errors high). vstep_k = float(v_step_fit) / 1000.0 vsp_k = ( float(vel_span_m_s_per_pixel) / 1000.0 if vel_span_m_s_per_pixel and np.isfinite(vel_span_m_s_per_pixel) and vel_span_m_s_per_pixel > 0 else vstep_k ) vk_span_km = float(np.nanmax(vk) - np.nanmin(vk)) if vk.size > 1 else 0.0 # Short / line-window grids: cap LM pass half-widths to a fraction of the actual # velocity span. Otherwise default pass widths (~hundreds of km) flatten the CCF in the # fit window when ``ccf_line_mask_stored_negated`` uses a fixed baseline, or bias free-baseline # fits that relied on this cap alone. narrow_v_for_hw_cap = ( vk_span_km > 0.0 and math.isfinite(vk_span_km) and (free_bl or bool(ccf_line_mask_stored_negated)) ) if narrow_v_for_hw_cap: eps_km = max(1e-6, 2.0 * vstep_k) hw_cap1 = max(eps_km, 0.48 * vk_span_km) hw_cap2 = max(eps_km, 0.42 * vk_span_km) hw1_km = min(float(cfg.pass1_half_width_km_s), float(hw_cap1)) hw2_km = min(float(cfg.pass2_half_width_km_s), float(hw_cap2)) else: hw1_km = float(cfg.pass1_half_width_km_s) hw2_km = float(cfg.pass2_half_width_km_s) def _lm(mo, ft): if hasattr(mo, "mean_0"): mk, sk = float(mo.mean_0.value), abs(float(mo.stddev_0.value)) mean_pname = "mean_0" else: mk, sk = float(mo.mean.value), abs(float(mo.stddev.value)) mean_pname = "mean" sm = None fi = getattr(ft, "fit_info", {}) or {} pc = fi.get("param_cov") if pc is None: pc = fi.get("cov_x") if pc is not None: try: pc = np.asarray(pc, np.float64) j = list(mo.param_names).index(mean_pname) if pc.shape[0] > j and pc[j, j] > 0: sm = float(math.sqrt(pc[j, j])) except Exception: pass return mk, sk, sm def _pass(center_km: float, hw_km: float, sd0: float, ft): lo, hi = center_km - hw_km, center_km + hw_km sel = (vk >= lo) & (vk <= hi) if not np.any(sel): return None, np.array([]), float("nan"), float("nan"), 0.0, False, {}, np.array([]), np.array([]) gx0 = vk[sel] gy00 = y[sel] fin = np.isfinite(gx0) & np.isfinite(gy00) gx0, gy00 = gx0[fin], gy00[fin] if gy00.size < cfg.min_points: return None, gx0, float("nan"), float("nan"), 0.0, False, {}, np.array([]), np.array([]) wts0 = None used_pw = False if y_err_ok is not None: ge = np.asarray(y_err_ok[sel], np.float64)[fin] good_w = np.isfinite(ge) & (ge > 0) if int(np.count_nonzero(good_w)) >= cfg.min_points: med_e = float(np.nanmedian(ge[good_w])) floor = max(med_e * 1e-6, 1e-30) ge_safe = np.where(good_w, ge, floor) wts0 = 1.0 / (ge_safe * ge_safe) used_pw = True n_start = int(gx0.size) min_keep = max(cfg.min_points, int(math.ceil(cfg.sigma_clip_min_keep_frac * n_start))) clip_info: dict = { "sigma_clip": bool(cfg.sigma_clip_enable), "iterations": 0, "n_start": n_start, "n_final": n_start, "prefit_unclipped_passes": int(cfg.sigma_clip_unclipped_prefit_passes), } def _one_fit(gx: np.ndarray, gy0: np.ndarray, wts: np.ndarray | None): ys = _levmar_ccf_y_scale(gy0) gy = np.asarray(gy0, dtype=np.float64) * ys if free_bl: bg_raw = float(np.nanmedian(np.asarray(gy0, dtype=np.float64))) if not np.isfinite(bg_raw): bg_raw = 0.0 else: bg_raw = _ccf_background_sigma_clipped_median( np.asarray(gy0, dtype=np.float64) ) if not np.isfinite(bg_raw): bg_raw = float(np.nanmedian(gy0)) b0 = float(bg_raw * ys) gy_det = gy - b0 span = abs(float(np.nanmax(gy_det) - np.nanmin(gy_det))) * 100.0 amp = ( max(-1e7, float(np.nanmin(gy_det)) - span) if profile == "emission" else min(1e7, float(np.nanmax(gy_det)) + span) ) if bool(ccf_line_mask_stored_negated): amp = max(float(amp), 1e-30) amp_floor_s = 0.0 if free_bl and (bool(ccf_line_mask_stored_negated) or profile == "absorption"): amp_floor_s = _ccf_gaussian_amp_floor_free_baseline_scaled(gy_det, ys) amp = max(float(amp), 2.0 * amp_floor_s) init = Gaussian1D(amplitude=amp, mean=center_km, stddev=sd0) + Const1D(amplitude=b0) if free_bl and (bool(ccf_line_mask_stored_negated) or profile == "absorption"): init.amplitude_0.min = float(amp_floor_s) elif bool(ccf_line_mask_stored_negated): init.amplitude_0.min = 0.0 if not free_bl: init.amplitude_1.fixed = True gx_lo = float(np.min(gx)) gx_hi = float(np.max(gx)) if gx_hi > gx_lo and hasattr(init, "mean_0"): init.mean_0.min = gx_lo init.mean_0.max = gx_hi mi = int(max(50, min(int(cfg.levmar_maxiter), 50_000))) if wts is not None: w_eff = np.asarray(wts, dtype=np.float64) / (ys * ys) return _levmar_lsq_fit(ft, init, gx, gy, weights=w_eff, maxiter=mi) return _levmar_lsq_fit(ft, init, gx, gy, maxiter=mi) gx_w = gx0 gy0_w = gy00 wts_w = wts0 best_g = None best_bmed = 0.0 best_gx = gx_w snap_gy0 = np.array([], dtype=np.float64) snap_ge = np.array([], dtype=np.float64) try: prefit = max(0, int(cfg.sigma_clip_unclipped_prefit_passes)) if cfg.sigma_clip_enable: clip_max = max(0, int(cfg.sigma_clip_max_iter)) total_it = prefit + clip_max else: clip_max = 0 total_it = max(1, prefit) if prefit > 0 else 1 for it in range(total_it): if gx_w.size < cfg.min_points: break g = _one_fit(gx_w, gy0_w, wts_w) pred = np.asarray(g(gx_w), dtype=np.float64) resid = gy0_w - pred best_g = g best_bmed = ( float(g.amplitude_1.value) if hasattr(g, "amplitude_1") else float(np.nanmedian(gy0_w)) ) best_gx = gx_w snap_gy0 = np.asarray(gy0_w, dtype=np.float64).copy() if wts_w is not None: snap_ge = (1.0 / np.sqrt(np.maximum(wts_w, 1e-300))).astype(np.float64) else: snap_ge = np.full(snap_gy0.shape, np.nan, dtype=np.float64) clip_info["iterations"] = it + 1 if not cfg.sigma_clip_enable: continue if it >= total_it - 1: break # Unclipped χ² passes: refit on full window only (no point removal). if it < prefit: continue # Sigma-clipping refinement (relaxed threshold for first few clip rounds). clip_idx = it - prefit sigma_mult = ( float(cfg.sigma_clip_n_sigma_relaxed) if clip_idx < int(cfg.sigma_clip_relax_first_clip_iters) else float(cfg.sigma_clip_n_sigma) ) med_r = float(np.median(resid)) mad = float(np.median(np.abs(resid - med_r))) sig_rob = 1.4826 * mad span_y = float(np.nanmax(resid) - np.nanmin(resid)) if resid.size else 1.0 sig_rob = max(sig_rob, 1e-9 * max(abs(span_y), 1.0)) thr = float(sigma_mult) * sig_rob keep = np.abs(resid) <= thr n_kept = int(np.count_nonzero(keep)) if n_kept >= gx_w.size: break if n_kept < min_keep: break gx_w = gx_w[keep] gy0_w = gy0_w[keep] if wts_w is not None: wts_w = wts_w[keep] clip_info["n_final"] = int(best_gx.size) if best_g is not None else 0 if best_g is None: return ( None, gx0, lo * 1000.0, hi * 1000.0, 0.0, used_pw, clip_info, np.array([]), np.array([]), ) return ( best_g, best_gx, lo * 1000.0, hi * 1000.0, best_bmed, used_pw, clip_info, snap_gy0, snap_ge, ) except Exception: return ( None, gx0, lo * 1000.0, hi * 1000.0, 0.0, used_pw, clip_info, np.array([]), np.array([]), ) def _gradient_ccf_err_km(fw_km: float, rv0_km: float) -> float: v = np.asarray(vk, np.float64).ravel() c = np.asarray(y, np.float64).ravel() m = np.isfinite(v) & np.isfinite(c) v, c = v[m], c[m] if v.size < 3 or fw_km <= 0: return 0.0 dv = np.diff(np.sort(v)) pos = dv[(dv > 0) & np.isfinite(dv)] vs = float(np.min(pos)) if pos.size > 0 else 0.0 if vs <= 0: return 0.0 nsp = 1.0 if not (np.isfinite(vsp_k) and vsp_k > 0) else vs / vsp_k s2 = (v >= rv0_km - fw_km * 0.5) & (v <= rv0_km + fw_km * 0.5) vf, cf = v[s2], c[s2] if cf.size == 0 or np.any(cf < 0): return 0.0 ns = np.sqrt(np.maximum(cf, 1e-30)) g = np.gradient(cf, vf) top = float(np.sqrt(np.sum((g / ns) ** 2))) bot = float(np.sqrt(np.sum(cf))) if top <= 0 or bot <= 0: return 0.0 return 1.0 / ((top / bot) * (nsp**0.5) * bot) def _ok_err(e: float, sig: float, vstep: float) -> bool: """ Accept finite, positive formal errors. Reject only non-finite values, non-positive values, or numerical blow-ups. When the fitted Gaussian width ``sig`` (m/s) is known and positive, reject covariances vastly larger than ``max(100·σ, 25·vstep)`` (unphysical vs. the fitted line width). There is **no** upper cap at ~200 km/s tied to velocity grid spacing (that spacing used to reject ``e > 5000·vstep`` and masked valid large uncertainties). """ if not (math.isfinite(e) and e > 0): return False if e > 1.0e15: return False if sig > 0 and e > max(100.0 * sig, 25.0 * max(vstep, 1e-9)): return False return True ft1 = fitting.LevMarLSQFitter() g1, gx1, vlo1, vhi1, med1, pw1, clip1, gy01, ge1 = _pass( rv_gk, hw1_km, cfg.initial_stddev_km_s, ft1 ) if g1 is None or gx1.size < cfg.min_points: fp_ctx: dict = { "fit_stage": "pass1", "reason": "LevMar did not return a usable model, or post-window sample count " "fell below min_points", "g1_is_none": g1 is None, "pass1_fit_sample_count": int(gx1.size), "min_points": int(cfg.min_points), "seed_mean_km_s": float(rv_gk), "pass1_half_width_km_s": float(hw1_km), "fit_window_m_s_lo": float(vlo1) if np.isfinite(vlo1) else None, "fit_window_m_s_hi": float(vhi1) if np.isfinite(vhi1) else None, "ccf_profile": profile, "velocity_grid_m_s_min": float(vm.min()), "velocity_grid_m_s_max": float(vm.max()), "n_velocity_points": int(vm.size), "v_step_effective_m_s": float(v_step_fit), "velocity_subsample_stride": int(subsample_stride), "ccf_fit_free_baseline": bool(free_bl), } if isinstance(clip1, dict) and clip1: fp_ctx["sigma_clip_iterations"] = int(clip1.get("iterations", 0)) fp_ctx["sigma_clip_n_start"] = int(clip1.get("n_start", 0)) fp_ctx["sigma_clip_n_final"] = int(clip1.get("n_final", 0)) return _fail("first-pass fit failed", **fp_ctx) m1k, _, _ = _lm(g1, ft1) if not (float(gx1.min()) <= m1k <= float(gx1.max())): gx_min, gx_max = float(gx1.min()), float(gx1.max()) ow_ctx = { "fit_stage": "pass1_post_lm", "reason": "LevMar Gaussian mean (km/s) lies outside the velocity abscissa of " "samples retained in the pass-1 window (after any sigma-clipping)", "fitted_mean_km_s": float(m1k), "fit_samples_v_km_min": gx_min, "fit_samples_v_km_max": gx_max, "fit_window_m_s_lo": float(vlo1), "fit_window_m_s_hi": float(vhi1), "pass1_half_width_km_s": float(hw1_km), "n_points_in_pass1_window": int(gx1.size), "seed_mean_km_s": float(rv_gk), "ccf_profile": profile, "velocity_grid_m_s_min": float(vm.min()), "velocity_grid_m_s_max": float(vm.max()), "n_velocity_points": int(vm.size), "v_step_effective_m_s": float(v_step_fit), "velocity_subsample_stride": int(subsample_stride), "ccf_y_min": float(np.nanmin(y)), "ccf_y_max": float(np.nanmax(y)), "ccf_fit_free_baseline": bool(free_bl), } if not math.isfinite(m1k): ow_ctx["mean_side"] = "non_finite_mean" elif m1k < gx_min: ow_ctx["mean_offset_km_s"] = float(gx_min - m1k) ow_ctx["mean_side"] = "below_sample_min" elif m1k > gx_max: ow_ctx["mean_offset_km_s"] = float(m1k - gx_max) ow_ctx["mean_side"] = "above_sample_max" if isinstance(clip1, dict): ow_ctx["sigma_clip_iterations"] = int(clip1.get("iterations", 0)) ow_ctx["sigma_clip_n_start"] = int(clip1.get("n_start", 0)) ow_ctx["sigma_clip_n_final"] = int(clip1.get("n_final", 0)) return _fail("mean outside window", **ow_ctx) best_g, best_ft, best_gx, best_med, best_vlo, best_vhi = g1, ft1, gx1, med1, vlo1, vhi1 used_pw_fit = pw1 clip_used = clip1 snap_y0, snap_ge = gy01, ge1 pw = 1 if two_pass: ft2 = fitting.LevMarLSQFitter() g2, gx2, vlo2, vhi2, med2, pw2, clip2, gy02, ge02 = _pass( m1k, hw2_km, float(np.clip(cfg.initial_stddev_km_s, 0.05, 200.0)), ft2, ) if g2 is not None and gx2.size >= cfg.min_points: m2k, _, _ = _lm(g2, ft2) r2 = m2k * 1000.0 if vlo2 <= r2 <= vhi2 and float(gx2.min()) <= m2k <= float(gx2.max()): best_g, best_ft, best_gx, best_med, best_vlo, best_vhi = g2, ft2, gx2, med2, vlo2, vhi2 used_pw_fit = pw2 clip_used = clip2 snap_y0, snap_ge = gy02, ge02 pw = 2 mk, sk, sigc = _lm(best_g, best_ft) rv_ms, sig_ms = float(mk * 1000.0), float(sk * 1000.0) vstep = float(v_step_fit) # LM can drive Gaussian σ → ~0; formal covariance on the mean then hits ~1e-16 m/s while # _ok_err still accepts it (bound uses max(100·σ, 25·vstep)). Treat that as non-physical. lm_width_plausible = math.isfinite(sig_ms) and sig_ms >= max(1e-15, 1e-12 * vstep) sig_for_fb_ms = ( float(sig_ms) if lm_width_plausible else max(vstep, 1e-12) if math.isfinite(vstep) and vstep > 0 else max(float(sig_ms), 1e-12) ) fw_km = 2.0 * (hw2_km if pw == 2 else hw1_km) ek = _gradient_ccf_err_km(fw_km, mk) ek_ms = float(ek * 1000.0) ek_ok = ek > 0 and np.isfinite(ek_ms) and _ok_err(ek_ms, sig_ms, vstep) cov_ms = ( float(sigc * 1000.0) if (sigc is not None and np.isfinite(sigc) and float(sigc) > 0) else float("nan") ) cov_ok = math.isfinite(cov_ms) and cov_ms > 0 and _ok_err(cov_ms, sig_ms, vstep) if not lm_width_plausible: cov_ok = False n_fit = max(int(best_gx.size), 1) rv_err_fb = float(sig_for_fb_ms / math.sqrt(float(n_fit))) if n_good is not None and int(n_good) > 0: rv_err_fb = max(rv_err_fb, float(sig_for_fb_ms / math.sqrt(float(n_good)))) comb = str(cfg.rv_err_cov_combine).lower().strip() if comb not in ("min", "max"): comb = "max" used_gradient = used_cov = used_fb = False if cov_ok and ek_ok: rv_err_ms = min(cov_ms, ek_ms) if comb == "min" else max(cov_ms, ek_ms) used_gradient = True used_cov = True msg = f"{'min' if comb == 'min' else 'max'}(gradient ccf_error, LevMar cov)" elif cov_ok: rv_err_ms = cov_ms used_cov = True msg = "LevMar cov" elif ek_ok: rv_err_ms = ek_ms used_gradient = True msg = "gradient ccf_error" else: rv_err_ms = rv_err_fb used_fb = True if ek > 0 and np.isfinite(ek): msg = "σ/√n (gradient ccf_error implausible)" elif sigc is not None and np.isfinite(float(sigc)) and float(sigc) > 0: msg = "σ/√n (LevMar cov implausible)" else: msg = "σ/√n fallback" used_boot = False boot_sig = float("nan") n_bs = int(cfg.rv_err_bootstrap_samples) if ( n_bs > 0 and snap_ge.size == snap_y0.size and snap_y0.size > 0 and np.any(np.isfinite(snap_ge) & (snap_ge > 0)) ): rng = np.random.default_rng(cfg.rv_err_bootstrap_seed) _sd_km = ( abs(float(best_g.stddev_0.value)) if hasattr(best_g, "stddev_0") else abs(float(best_g.stddev.value)) ) boot_sig = _bootstrap_gaussian_rv_std_m_s( best_gx, snap_y0, snap_ge, seed_mean_km=float(mk), seed_std_km=max(_sd_km, 1e-9), profile=profile, n_samples=n_bs, rng=rng, maxiter=int(max(50, min(int(cfg.levmar_maxiter), 50_000))), free_baseline=free_bl, ccf_line_mask_stored_negated=ccf_line_mask_stored_negated, ) if math.isfinite(boot_sig) and boot_sig > 0: used_boot = True rv_err_ms = max(rv_err_ms, boot_sig) slope_prop_ms = float("nan") applied_slope_floor = False if snap_y0.size >= 5 and best_gx.size == snap_y0.size: se_slope = snap_ge if np.any(np.isfinite(snap_ge) & (snap_ge > 0)) else None slope_prop_ms = _rv_err_slope_propagation_m_s(best_gx * 1000.0, snap_y0, se_slope) if math.isfinite(slope_prop_ms) and slope_prop_ms > 0 and not used_cov: rv_err_ms = max(rv_err_ms, slope_prop_ms) applied_slope_floor = True rv_err_ms = max(rv_err_ms, _ccf_rv_err_numeric_floor(vstep)) ys_snap = _levmar_ccf_y_scale(snap_y0) _bg_robust = float(_ccf_background_sigma_clipped_median(snap_y0)) if hasattr(best_g, "amplitude_0"): _amp = float(best_g.amplitude_0.value) / ys_snap if free_bl and hasattr(best_g, "amplitude_1"): _baseline = float(best_g.amplitude_1.value) / ys_snap else: _baseline = _bg_robust if not np.isfinite(_baseline): _baseline = float(best_g.amplitude_1.value) / ys_snap else: _amp = float(best_g.amplitude.value) _baseline = float(best_med) amplitude_from_peak_fallback = False if ( bool(ccf_line_mask_stored_negated) and _amp <= 0.0 and snap_y0.size > 0 and hasattr(best_g, "amplitude_0") ): peak = float(np.nanmax(snap_y0)) base = float(_baseline) if np.isfinite(float(_baseline)) else peak ph = peak - base if math.isfinite(ph) and ph > 0.0: _amp = ph amplitude_from_peak_fallback = True params = { "amplitude": _amp, "v0": rv_ms, "sigma": sig_ms, "baseline": _baseline, } diag = { "fit_ok": True, "ccf_line_mask_forced_peak_up_profile": bool(forced_line_mask_peak_up), "used_covariance_for_error": used_cov, "used_sigma_fallback": used_fb, "used_gradient_ccf_error": used_gradient, "used_ccf_pointwise_error": bool(used_pw_fit), "message": msg, "ccf_velocity_grid_min_m_s": float(np.min(vm)), "ccf_velocity_grid_max_m_s": float(np.max(vm)), "fit_v_lo": float(best_vlo), "fit_v_hi": float(best_vhi), "profile": profile, "fit_pass_used": pw, "ccf_dir_style": "up" if profile == "absorption" else "down", "sigma_clip_enabled": bool(clip_used.get("sigma_clip", cfg.sigma_clip_enable)), "sigma_clip_iterations": int(clip_used.get("iterations", 0)), "sigma_clip_n_points_initial": int(clip_used.get("n_start", 0)), "sigma_clip_n_points_final": int(clip_used.get("n_final", best_gx.size)), "rv_err_bootstrap_sigma_m_s": boot_sig, "used_rv_err_bootstrap": used_boot, "rv_err_cov_combine": comb, "lm_gaussian_width_plausible": bool(lm_width_plausible), "rv_err_slope_propagation_m_s": slope_prop_ms, "applied_slope_propagation_floor": bool(applied_slope_floor), "velocity_fit_subsample_stride": int(subsample_stride), "ccf_background_sigma_clipped_median": ( float(_bg_robust) if np.isfinite(_bg_robust) and hasattr(best_g, "amplitude_0") else float(_baseline) ), "ccf_fit_free_baseline": bool(free_bl), "ccf_amplitude_from_peak_fallback": bool(amplitude_from_peak_fallback), } if free_bl and hasattr(best_g, "amplitude_1") and np.isfinite(_bg_robust): diag["ccf_baseline_lm_median_space"] = float(_baseline) diag.update(_ccf_line_mask_diag) if gaussian_seed_mean_m_s is not None and math.isfinite(float(gaussian_seed_mean_m_s)): diag["gaussian_seed_mean_m_s"] = float(gaussian_seed_mean_m_s) return (rv_ms, rv_err_ms, params, diag) if return_params else (rv_ms, rv_err_ms)
# ============================================================================= # Numba per-chunk log-λ CCF + Python Gaussian RV (many orders at once) # =============================================================================
[docs] def _ccf_rv_from_ccf( v_grid: np.ndarray, ccf: np.ndarray, v_step: float, n_good: int, vel_span_m_s_per_pixel: float | None = None, *, min_good_pixels: int = 10, ccf_bisector_config: CCFBisectorConfig | None = None, ) -> tuple[float, float]: """Gaussian fit to CCF for final RV; else grid peak / HWHM. ``ccf_bisector_config`` is retained for API compatibility. Bisector refine is not used for the reported RV. """ ccf = np.asarray(ccf, dtype=np.float64) n_vel = len(ccf) if n_good < int(min_good_pixels) or n_vel < 3 or not np.any(np.isfinite(ccf)): return np.nan, np.nan ccf_max = float(np.nanmax(ccf)) ccf_min = float(np.nanmin(ccf)) i_max = int(np.nanargmax(ccf)) rv = float(v_grid[i_max]) if not np.isfinite(ccf_max): return np.nan, np.nan if ccf_max <= ccf_min or not np.isfinite(ccf_min): return rv, float(max(v_step * 2.0, _ccf_rv_err_numeric_floor(v_step))) vsp = ( float(vel_span_m_s_per_pixel) if vel_span_m_s_per_pixel is not None and np.isfinite(vel_span_m_s_per_pixel) and vel_span_m_s_per_pixel > 0 else None ) rv_fit, err_fit, params, _diag = fit_ccf_rv( v_grid, ccf, v_step, n_good=n_good, vel_span_m_s_per_pixel=vsp, return_params=True, ) if np.isfinite(rv_fit) and np.isfinite(err_fit) and err_fit > 0.0: return float(rv_fit), float(err_fit) half = (ccf_max + ccf_min) / 2.0 below = np.where(ccf[:i_max] <= half)[0] above = np.where(ccf[i_max:] <= half)[0] left = int(below[-1]) if len(below) else 0 right = i_max + int(above[0]) if len(above) else n_vel - 1 hwhm = (right - left) * v_step * 0.5 ng = max(int(n_good), 1) return rv, float(max(hwhm / math.sqrt(float(ng)), _ccf_rv_err_numeric_floor(v_step)))
[docs] @njit(cache=True) def _ccf_chunk_ccf_numba( ln_lam: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, good: np.ndarray, template_ln: np.ndarray, template_flux: np.ndarray, v_min: float, v_max: float, v_step: float, ccf_out: np.ndarray, min_good_pixels: int, zb: float, ) -> int: """ Weighted cross-correlation CCF(v) for one chunk. Writes ``ccf_out`` (length n_vel); returns count of good spectral pixels (for error scaling). """ n_good = 0 for i in range(len(good)): if good[i]: n_good += 1 if n_good < min_good_pixels: return n_good n_pix = len(ln_lam) # Inverse-variance weights (same as 1/spec_err² with floor); reused for every v. inv_w = np.empty(n_pix) for i in range(n_pix): if good[i] and np.isfinite(spec_err[i]) and spec_err[i] > 0: inv_w[i] = 1.0 / max(spec_err[i] * spec_err[i], 1e-30) else: inv_w[i] = 0.0 n_vel = len(ccf_out) for i in range(n_vel): ccf_out[i] = np.nan zb1 = 1.0 + zb if zb1 <= 0.0: zb1 = 1.0 # One CCF sample per trial velocity: shift template in lnλ, interpolate to data pixels. for iv in range(n_vel): v = v_min + iv * v_step delta_ln = math.log((1.0 + v / C_M_S) / zb1) t_ln_shifted = template_ln + delta_ln t_at_data = np.interp(ln_lam, t_ln_shifted, template_flux) # Weighted means of data and template at this v (same pixels as masked_ccf_rv). sum_w = 0.0 sum_d = 0.0 sum_t = 0.0 n_use = 0 for i in range(n_pix): if ( good[i] and inv_w[i] > 0.0 and np.isfinite(t_at_data[i]) and t_at_data[i] != 0.0 ): w = inv_w[i] sum_w += w sum_d += spec[i] * w sum_t += t_at_data[i] * w n_use += 1 if n_use < 5: continue d_mean = sum_d / sum_w t_mean = sum_t / sum_w # Weighted covariance (mean-subtracted); same definition as Python masked_ccf_rv. cov = 0.0 for i in range(n_pix): if ( good[i] and inv_w[i] > 0.0 and np.isfinite(t_at_data[i]) and t_at_data[i] != 0.0 ): w = inv_w[i] cov += (spec[i] - d_mean) * (t_at_data[i] - t_mean) * w ccf_out[iv] = cov / sum_w return n_good
[docs] @njit(cache=True) def _ccf_chunk_ccf_numba_vgrid( ln_lam: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, good: np.ndarray, template_ln: np.ndarray, template_flux: np.ndarray, v_grid: np.ndarray, ccf_out: np.ndarray, min_good_pixels: int, zb: float, ) -> int: """Same as :func:`_ccf_chunk_ccf_numba` but samples at arbitrary ``v_grid`` (m/s).""" n_good = 0 for i in range(len(good)): if good[i]: n_good += 1 if n_good < min_good_pixels: return n_good n_pix = len(ln_lam) inv_w = np.empty(n_pix) for i in range(n_pix): if good[i] and np.isfinite(spec_err[i]) and spec_err[i] > 0: inv_w[i] = 1.0 / max(spec_err[i] * spec_err[i], 1e-30) else: inv_w[i] = 0.0 n_vel = len(ccf_out) for i in range(n_vel): ccf_out[i] = np.nan zb1 = 1.0 + zb if zb1 <= 0.0: zb1 = 1.0 for iv in range(n_vel): v = float(v_grid[iv]) delta_ln = math.log((1.0 + v / C_M_S) / zb1) t_ln_shifted = template_ln + delta_ln t_at_data = np.interp(ln_lam, t_ln_shifted, template_flux) sum_w = 0.0 sum_d = 0.0 sum_t = 0.0 n_use = 0 for i in range(n_pix): if ( good[i] and inv_w[i] > 0.0 and np.isfinite(t_at_data[i]) and t_at_data[i] != 0.0 ): w = inv_w[i] sum_w += w sum_d += spec[i] * w sum_t += t_at_data[i] * w n_use += 1 if n_use < 5: continue d_mean = sum_d / sum_w t_mean = sum_t / sum_w cov = 0.0 for i in range(n_pix): if ( good[i] and inv_w[i] > 0.0 and np.isfinite(t_at_data[i]) and t_at_data[i] != 0.0 ): w = inv_w[i] cov += (spec[i] - d_mean) * (t_at_data[i] - t_mean) * w ccf_out[iv] = cov / sum_w return n_good
[docs] @njit(parallel=True, cache=True) def _process_all_orders_ccf_numba( wave_2d: np.ndarray, spec_2d: np.ndarray, spec_err_2d: np.ndarray, dq_2d: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, order_indices: np.ndarray, n_chunks_per_order: np.ndarray, chunk_start: np.ndarray, v_min: float, v_max: float, v_step: float, n_vel: int, all_ccf: np.ndarray, all_n_good: np.ndarray, all_wl: np.ndarray, min_good_pixels: int, zb: float, ) -> None: """ Parallel per-order CCF fill: writes ``all_ccf[chunk, :]``, ``all_n_good[chunk]``, ``all_wl[chunk]``. RV fit in Python via :func:`fit_ccf_rv`. """ n_processed = len(order_indices) for idx in prange(n_processed): oi = order_indices[idx] w = wave_2d[oi] s = spec_2d[oi] e = spec_err_2d[oi] d = dq_2d[oi] n_pix = len(w) # Pixel usable for CCF: not DQ-bad, finite flux and positive error. mask = np.empty(n_pix, dtype=np.bool_) for i in range(n_pix): mask[i] = (d[i] & do_not_use) != 0 good = np.empty(n_pix, dtype=np.bool_) for i in range(n_pix): good[i] = not mask[i] and np.isfinite(s[i]) and np.isfinite(e[i]) and e[i] > 0 w_min = np.nanmin(w) w_max = np.nanmax(w) ln_min = np.log(w_min) - 0.01 ln_max = np.log(w_max) + 0.01 n_tpl = 0 for i in range(len(template_ln)): if template_ln[i] >= ln_min and template_ln[i] <= ln_max: n_tpl += 1 if n_tpl < 20: continue # skip order: template would be too sparse after clip t_ln = np.empty(n_tpl) t_flux = np.empty(n_tpl) j = 0 for i in range(len(template_ln)): if template_ln[i] >= ln_min and template_ln[i] <= ln_max: t_ln[j] = template_ln[i] t_flux[j] = template_flux[i] j += 1 ccf_row = np.empty(n_vel) n_chunks = n_chunks_per_order[idx] start = chunk_start[idx] # Wavelength bins along the order; each bin gets one CCF vector. for k in range(n_chunks): lam_lo = w_min + k * (w_max - w_min) / n_chunks lam_hi = w_min + (k + 1) * (w_max - w_min) / n_chunks in_chunk = np.empty(n_pix, dtype=np.bool_) chunk_len = 0 for i in range(n_pix): if k == n_chunks - 1: in_chunk[i] = w[i] >= lam_lo and w[i] <= lam_hi else: in_chunk[i] = w[i] >= lam_lo and w[i] < lam_hi if in_chunk[i]: chunk_len += 1 wl_c = 0.5 * (lam_lo + lam_hi) all_wl[start + k] = wl_c if chunk_len < 20: all_n_good[start + k] = 0 continue ln_lam_c = np.empty(chunk_len) spec_c = np.empty(chunk_len) spec_err_c = np.empty(chunk_len) good_c = np.empty(chunk_len, dtype=np.bool_) j = 0 for i in range(n_pix): if in_chunk[i]: ln_lam_c[j] = np.log(w[i]) spec_c[j] = s[i] spec_err_c[j] = e[i] good_c[j] = good[i] j += 1 ng = _ccf_chunk_ccf_numba( ln_lam_c, spec_c, spec_err_c, good_c, t_ln, t_flux, v_min, v_max, v_step, ccf_row, min_good_pixels, zb, ) all_n_good[start + k] = ng for iv in range(n_vel): all_ccf[start + k, iv] = ccf_row[iv]
[docs] @njit(parallel=True, cache=True) def _process_all_orders_ccf_numba_vgrid( wave_2d: np.ndarray, spec_2d: np.ndarray, spec_err_2d: np.ndarray, dq_2d: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, order_indices: np.ndarray, n_chunks_per_order: np.ndarray, chunk_start: np.ndarray, v_grid: np.ndarray, n_vel: int, all_ccf: np.ndarray, all_n_good: np.ndarray, all_wl: np.ndarray, min_good_pixels: int, zb: float, ) -> None: """Same as :func:`_process_all_orders_ccf_numba` but with an explicit ``v_grid`` (m/s).""" n_processed = len(order_indices) for idx in prange(n_processed): oi = order_indices[idx] w = wave_2d[oi] s = spec_2d[oi] e = spec_err_2d[oi] d = dq_2d[oi] n_pix = len(w) mask = np.empty(n_pix, dtype=np.bool_) for i in range(n_pix): mask[i] = (d[i] & do_not_use) != 0 good = np.empty(n_pix, dtype=np.bool_) for i in range(n_pix): good[i] = not mask[i] and np.isfinite(s[i]) and np.isfinite(e[i]) and e[i] > 0 w_min = np.nanmin(w) w_max = np.nanmax(w) ln_min = np.log(w_min) - 0.01 ln_max = np.log(w_max) + 0.01 n_tpl = 0 for i in range(len(template_ln)): if template_ln[i] >= ln_min and template_ln[i] <= ln_max: n_tpl += 1 if n_tpl < 20: continue t_ln = np.empty(n_tpl) t_flux = np.empty(n_tpl) j = 0 for i in range(len(template_ln)): if template_ln[i] >= ln_min and template_ln[i] <= ln_max: t_ln[j] = template_ln[i] t_flux[j] = template_flux[i] j += 1 ccf_row = np.empty(n_vel) n_chunks = n_chunks_per_order[idx] start = chunk_start[idx] for k in range(n_chunks): lam_lo = w_min + k * (w_max - w_min) / n_chunks lam_hi = w_min + (k + 1) * (w_max - w_min) / n_chunks in_chunk = np.empty(n_pix, dtype=np.bool_) chunk_len = 0 for i in range(n_pix): if k == n_chunks - 1: in_chunk[i] = w[i] >= lam_lo and w[i] <= lam_hi else: in_chunk[i] = w[i] >= lam_lo and w[i] < lam_hi if in_chunk[i]: chunk_len += 1 wl_c = 0.5 * (lam_lo + lam_hi) all_wl[start + k] = wl_c if chunk_len < 20: all_n_good[start + k] = 0 continue ln_lam_c = np.empty(chunk_len) spec_c = np.empty(chunk_len) spec_err_c = np.empty(chunk_len) good_c = np.empty(chunk_len, dtype=np.bool_) j = 0 for i in range(n_pix): if in_chunk[i]: ln_lam_c[j] = np.log(w[i]) spec_c[j] = s[i] spec_err_c[j] = e[i] good_c[j] = good[i] j += 1 ng = _ccf_chunk_ccf_numba_vgrid( ln_lam_c, spec_c, spec_err_c, good_c, t_ln, t_flux, v_grid, ccf_row, min_good_pixels, zb, ) all_n_good[start + k] = ng for iv in range(n_vel): all_ccf[start + k, iv] = ccf_row[iv]
[docs] def _process_all_orders_rvs_numba_single_grid( wave_2d: np.ndarray, spec_2d: np.ndarray, spec_err_2d: np.ndarray, dq_2d: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, order_indices: np.ndarray, n_chunks_per_order: np.ndarray, chunk_start: np.ndarray, v_min: float, v_max: float, v_step: float, *, return_ccf: bool = False, numba_threads: int | None = None, min_good_pixels: int = 10, zb: float = 0.0, ) -> ( tuple[np.ndarray, np.ndarray, np.ndarray] | tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] ): """Single uniform velocity grid: Numba CCF fill + per-chunk Gaussian RV.""" n_processed = len(order_indices) total_chunks = int(chunk_start[n_processed - 1] + n_chunks_per_order[n_processed - 1]) n_vel = int((v_max - v_min) / v_step) + 1 # Phase A — Numba fills CCF matrix (memory: total_chunks × n_vel). all_ccf = np.full((total_chunks, n_vel), np.nan, dtype=np.float64) all_n_good = np.zeros(total_chunks, dtype=np.int32) all_wl = np.empty(total_chunks, dtype=np.float64) all_wl[:] = np.nan all_rvs = np.empty(total_chunks, dtype=np.float64) all_rvs[:] = np.nan all_rv_errs = np.empty(total_chunks, dtype=np.float64) all_rv_errs[:] = np.nan nt = numba_threads if numba_threads is not None else 1 logger.info( "CCF (Numba): starting CCF matrix fill total_chunks=%d n_vel=%d numba_threads=%d", total_chunks, n_vel, nt, ) _process_all_orders_ccf_numba( wave_2d, spec_2d, spec_err_2d, dq_2d, do_not_use, template_ln, template_flux, window_size_um, order_indices, n_chunks_per_order, chunk_start, v_min, v_max, v_step, n_vel, all_ccf, all_n_good, all_wl, int(min_good_pixels), float(zb), ) logger.info( "CCF (Numba): CCF matrix fill complete total_chunks=%d n_vel=%d", total_chunks, n_vel, ) # Phase B — Gaussian fit per chunk row in Python (cannot run inside Numba). v_grid = v_min + np.arange(n_vel, dtype=np.float64) * v_step logger.info( "CCF (Python): starting per-chunk Gaussian RV fits total_chunks=%d", total_chunks, ) n_fit_rows = 0 mg = int(min_good_pixels) for i in range(total_chunks): if all_n_good[i] < mg: continue n_fit_rows += 1 wl_c = float(all_wl[i]) vspan = dv_per_pixel_m_s(wl_c) if not np.isfinite(vspan): vspan = None rv, rv_err = _ccf_rv_from_ccf( v_grid, all_ccf[i], v_step, int(all_n_good[i]), vel_span_m_s_per_pixel=vspan, min_good_pixels=mg, ) all_rvs[i] = rv all_rv_errs[i] = rv_err logger.info( "CCF (Python): per-chunk Gaussian fits complete rows_fitted=%d of total_chunks=%d", n_fit_rows, total_chunks, ) if return_ccf: return all_rvs, all_rv_errs, all_wl, all_ccf, v_grid, all_n_good return all_rvs, all_rv_errs, all_wl
[docs] def _process_all_orders_rvs_numba_single_vgrid( wave_2d: np.ndarray, spec_2d: np.ndarray, spec_err_2d: np.ndarray, dq_2d: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, order_indices: np.ndarray, n_chunks_per_order: np.ndarray, chunk_start: np.ndarray, v_grid: np.ndarray, *, return_ccf: bool = False, numba_threads: int | None = None, min_good_pixels: int = 10, zb: float = 0.0, ) -> ( tuple[np.ndarray, np.ndarray, np.ndarray] | tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] ): """Explicit ``v_grid`` (uniform centered or custom): Numba CCF fill + per-chunk Gaussian RV.""" v_grid = np.asarray(v_grid, dtype=np.float64).ravel() n_vel = int(v_grid.shape[0]) if n_vel < 2: raise ValueError("v_grid must contain at least two velocity samples (m/s)") v_step_fit = effective_ccf_v_step_for_fit(v_grid) n_processed = len(order_indices) total_chunks = int(chunk_start[n_processed - 1] + n_chunks_per_order[n_processed - 1]) all_ccf = np.full((total_chunks, n_vel), np.nan, dtype=np.float64) all_n_good = np.zeros(total_chunks, dtype=np.int32) all_wl = np.empty(total_chunks, dtype=np.float64) all_wl[:] = np.nan all_rvs = np.empty(total_chunks, dtype=np.float64) all_rvs[:] = np.nan all_rv_errs = np.empty(total_chunks, dtype=np.float64) all_rv_errs[:] = np.nan nt = numba_threads if numba_threads is not None else 1 logger.info( "CCF (Numba): starting CCF matrix fill (explicit v_grid) total_chunks=%d n_vel=%d " "numba_threads=%d", total_chunks, n_vel, nt, ) _process_all_orders_ccf_numba_vgrid( wave_2d, spec_2d, spec_err_2d, dq_2d, do_not_use, template_ln, template_flux, window_size_um, order_indices, n_chunks_per_order, chunk_start, v_grid, n_vel, all_ccf, all_n_good, all_wl, int(min_good_pixels), float(zb), ) logger.info( "CCF (Numba): CCF matrix fill complete total_chunks=%d n_vel=%d", total_chunks, n_vel, ) logger.info( "CCF (Python): starting per-chunk Gaussian RV fits total_chunks=%d", total_chunks, ) n_fit_rows = 0 mg = int(min_good_pixels) for i in range(total_chunks): if all_n_good[i] < mg: continue n_fit_rows += 1 wl_c = float(all_wl[i]) vspan = dv_per_pixel_m_s(wl_c) if not np.isfinite(vspan): vspan = None rv, rv_err = _ccf_rv_from_ccf( v_grid, all_ccf[i], v_step_fit, int(all_n_good[i]), vel_span_m_s_per_pixel=vspan, min_good_pixels=mg, ) all_rvs[i] = rv all_rv_errs[i] = rv_err logger.info( "CCF (Python): per-chunk Gaussian fits complete rows_fitted=%d of total_chunks=%d", n_fit_rows, total_chunks, ) if return_ccf: return all_rvs, all_rv_errs, all_wl, all_ccf, v_grid, all_n_good return all_rvs, all_rv_errs, all_wl
[docs] def process_all_orders_rvs_numba( wave_2d: np.ndarray, spec_2d: np.ndarray, spec_err_2d: np.ndarray, dq_2d: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, order_indices: np.ndarray, n_chunks_per_order: np.ndarray, chunk_start: np.ndarray, v_min: float, v_max: float, v_step: float, *, return_ccf: bool = False, numba_threads: int | None = None, ccf_center_m_s: float | None = None, ccf_half_window_m_s: float = 20000.0, min_good_pixels: int = 10, zb: float = 0.0, ) -> ( tuple[np.ndarray, np.ndarray, np.ndarray] | tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] ): """ High-throughput per-chunk RVs: Numba CCF grid, then SciPy Gaussian per chunk. Workhorse behind :func:`process_orders_rvs_numba_parallel`. When ``ccf_center_m_s`` is ``None``, uses a single grid ``(v_min, v_max, v_step)``. When ``ccf_center_m_s`` is set, uses a **uniform** centered window ``center ± ccf_half_window_m_s`` sampled at ``v_step`` (see :func:`build_centered_uniform_velocity_grid`). """ if ccf_center_m_s is None: return _process_all_orders_rvs_numba_single_grid( wave_2d, spec_2d, spec_err_2d, dq_2d, do_not_use, template_ln, template_flux, window_size_um, order_indices, n_chunks_per_order, chunk_start, v_min, v_max, v_step, return_ccf=return_ccf, numba_threads=numba_threads, min_good_pixels=int(min_good_pixels), zb=float(zb), ) vc = float(ccf_center_m_s) hw = float(ccf_half_window_m_s) vs = float(v_step) if not np.isfinite(vc) or not np.isfinite(hw) or hw <= 0: raise ValueError( "centered CCF: center and half-width must be finite and half-width > 0 (m/s)" ) if not np.isfinite(vs) or vs <= 0: raise ValueError("centered CCF: step must be finite and > 0 (m/s)") if vc + hw <= vc - hw: raise ValueError("centered CCF: velocity window is empty") v_grid = build_centered_uniform_velocity_grid(vc, hw, vs) logger.info( "CCF (Numba): centered uniform grid — center=%g half_width=%g step=%g → n_vel=%d", vc, hw, vs, int(v_grid.shape[0]), ) return _process_all_orders_rvs_numba_single_vgrid( wave_2d, spec_2d, spec_err_2d, dq_2d, do_not_use, template_ln, template_flux, window_size_um, order_indices, n_chunks_per_order, chunk_start, v_grid, return_ccf=return_ccf, numba_threads=numba_threads, min_good_pixels=int(min_good_pixels), zb=float(zb), )
[docs] def flat_chunk_echelle_orders( order_tasks: list, chunk_start: np.ndarray, n_flat: int, ) -> np.ndarray: """ Echelle order number for each flattened chunk index (same packing as :func:`process_orders_rvs_numba_parallel`). ``chunk_start[j]`` is the global flat index of the first chunk of ``order_tasks[j]`` (``(order_row_index, echelle_order_number)``). Parameters ---------- order_tasks : list of tuple ``(order_row_index, echelle_order_number)`` in the same order as used to build ``chunk_start`` and ``n_chunks_per_order``. chunk_start : np.ndarray Cumulative start index of each order’s chunks in the flattened ``all_rvs`` layout. n_flat : int Total number of chunk slots (rows) in the flattened arrays. Returns ------- np.ndarray ``dtype`` int64, length ``n_flat``. For each flat chunk index ``i``, the echelle order number of the order that owns that chunk, or ``-1`` where ``i`` is out of range. """ if n_flat <= 0 or not order_tasks: return np.array([], dtype=np.int64) chunk_start = np.asarray(chunk_start, dtype=np.int64) order_nums = np.array([int(t[1]) for t in order_tasks], dtype=np.int64) ii = np.arange(n_flat, dtype=np.int64) j = np.searchsorted(chunk_start, ii, side="right") - 1 valid = (j >= 0) & (j < len(order_tasks)) out = np.full(n_flat, -1, dtype=np.int64) out[valid] = order_nums[j[valid]] return out
[docs] def process_orders_rvs_numba_parallel( wave_2d: np.ndarray, spec_2d: np.ndarray, spec_err_2d: np.ndarray, dq_2d: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, order_tasks: list, max_cores: int | None = None, *, return_ccf: bool = False, ccf_v_min: float | None = None, ccf_v_max: float | None = None, ccf_v_step: float | None = None, ccf_center_m_s: float | None = None, ccf_half_window_m_s: float = 20000.0, min_good_pixels: int = 10, zb: float = 0.0, ) -> ( tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] | tuple[ np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, ] ): """ Stellar-RV fast path: many orders × wavelength chunks in one call. Flattens ``order_tasks`` into chunk index arrays, runs :func:`process_all_orders_rvs_numba` (Numba CCF + Python Gaussian fit per chunk), and optionally sets Numba thread count via ``max_cores``. Parameters ---------- wave_2d : np.ndarray, shape (n_orders, n_pix) Wavelength in micron. spec_2d, spec_err_2d : np.ndarray Flux and uncertainty per order. dq_2d : np.ndarray, uint32 Data quality flags. do_not_use : int Bit mask; pixels with ``(dq & do_not_use) != 0`` are excluded. template_ln, template_flux : np.ndarray Full stellar template. window_size_um : float Wavelength span per chunk (micron). order_tasks : list of tuple ``(order_row_index, order_number)`` for each order to include. max_cores : int, optional Numba parallel thread count for the order-parallel CCF loop. ``None`` or ``0`` uses all logical CPUs (see :func:`~hispecdrp.utils.parallelization_utils.resolve_numba_threads`). ``1`` forces single-threaded execution (reproducible, slower). return_ccf : bool, optional If ``True``, also return per-chunk CCF stacks, the velocity grid, per-chunk ``order_indices``, and per-chunk good-pixel counts for previews / RVCCF supplements (see implementation return tuple). ccf_v_min, ccf_v_max, ccf_v_step : float, optional Uniform CCF velocity range (m/s). When ``ccf_center_m_s`` is set, ``ccf_v_step`` is the sampling of the centered window (``ccf_v_min`` / ``ccf_v_max`` are unused). Defaults are ``V_MIN_DEFAULT_M_S``, ``V_MAX_DEFAULT_M_S``, ``V_STEP_DEFAULT_M_S``. ccf_center_m_s : float or None, optional When set, uses a uniform window ``center ± ccf_half_window_m_s`` at ``ccf_v_step``; see :func:`build_centered_uniform_velocity_grid`. ccf_half_window_m_s : float, optional Half-width (m/s) of the centered uniform window; default matches :class:`~hispecdrp.primitives.stellar_rv.stellar_rv_primitive.StellarRVPrimitive`. min_good_pixels : int, optional Minimum good spectral pixels per chunk for CCF evaluation and Gaussian RV fit (same role as ``ccf_min_good_pixels`` on :class:`~hispecdrp.primitives.stellar_rv.stellar_rv_primitive.StellarRVPrimitive`). zb : float, optional Barycentric factor :math:`z_b` in :math:`\\ln\\lambda` template shifts, :math:`\\Delta\\ln\\lambda = \\ln\\frac{1+v/c}{1+z_b}` (matches mask-line mapping when ``z_b`` is small). Returns ------- all_rvs : np.ndarray Per-chunk RV (m/s), 1-D flattened over all orders. all_rv_errs : np.ndarray Per-chunk uncertainty (m/s). all_wl : np.ndarray Chunk center wavelength (micron). n_chunks_per_order, chunk_start : np.ndarray Chunk layout (always returned). Use with :func:`flat_chunk_echelle_orders` to map flat chunk index → echelle order number. all_ccf, v_grid, order_indices, all_n_good : np.ndarray, optional Extra arrays when ``return_ccf`` is True (for preview / RVCCF supplement columns). Notes ----- **Performance:** Phase A (Numba ``prange`` over orders) fills ``total_chunks × n_vel`` with ``n_vel ≈ (v_max - v_min) / v_step``. Phase B runs :func:`fit_ccf_rv` per chunk in a serial Python loop. Dominant levers: ``numba_threads`` (``max_cores``) for Phase A, and optional coarser ``ccf_v_step`` if acceptable for the use case. """ if not order_tasks: empty = ( np.array([], dtype=np.float64), np.array([], dtype=np.float64), np.array([], dtype=np.float64), ) z64 = np.array([], dtype=np.int64) if return_ccf: return empty + ( np.zeros((0, 0), dtype=np.float64), np.array([], dtype=np.float64), np.array([], dtype=np.int32), z64, z64, z64, ) return empty + (z64, z64) wave_2d = np.asarray(wave_2d, dtype=np.float64) spec_2d = np.asarray(spec_2d, dtype=np.float64) spec_err_2d = np.asarray(spec_err_2d, dtype=np.float64) dq_2d = np.asarray(dq_2d, dtype=np.uint32) template_ln = np.asarray(template_ln, dtype=np.float64) template_flux = np.asarray(template_flux, dtype=np.float64) order_indices = np.array([oi for oi, _ in order_tasks], dtype=np.int64) n_chunks_per_order = np.array([ ccf_order_n_chunks_for_span( float(np.nanmax(wave_2d[oi]) - np.nanmin(wave_2d[oi])), float(window_size_um), ) for oi, _ in order_tasks ], dtype=np.int64) chunk_start = np.zeros(len(order_indices), dtype=np.int64) for i in range(1, len(order_indices)): chunk_start[i] = chunk_start[i - 1] + n_chunks_per_order[i - 1] nthr = resolve_numba_threads(max_cores) vm = float(V_MIN_DEFAULT_M_S if ccf_v_min is None else ccf_v_min) vx = float(V_MAX_DEFAULT_M_S if ccf_v_max is None else ccf_v_max) vs = float(V_STEP_DEFAULT_M_S if ccf_v_step is None else ccf_v_step) hyc = ccf_center_m_s centered = hyc is not None and np.isfinite(float(hyc)) if not centered: if not np.isfinite(vm) or not np.isfinite(vx) or not np.isfinite(vs) or vs <= 0: raise ValueError( "ccf_v_min, ccf_v_max must be finite and ccf_v_step must be finite and > 0" ) if vx <= vm: raise ValueError("ccf_v_max must be greater than ccf_v_min") total_chunks_layout = int(chunk_start[-1] + n_chunks_per_order[-1]) if centered: logger.info( "CCF: process_orders_rvs_numba_parallel centered uniform grid n_order_tasks=%d " "total_chunks=%d window_um=%.4f return_ccf=%s numba_threads=%d " "center=%.2f m/s half_width=%.2f step=%.4f", len(order_tasks), total_chunks_layout, window_size_um, return_ccf, nthr, float(hyc), float(ccf_half_window_m_s), float(vs), ) else: logger.info( "CCF: process_orders_rvs_numba_parallel n_order_tasks=%d total_chunks=%d " "window_um=%.4f return_ccf=%s numba_threads=%d " "v_grid_m_s=[%.0f, %.0f] step=%.1f", len(order_tasks), total_chunks_layout, window_size_um, return_ccf, nthr, vm, vx, vs, ) # Flattened (order, chunk) RV list; parallelized over orders inside Numba. with numba_thread_scope(max_cores): if centered: kw_h = dict( ccf_center_m_s=float(hyc), ccf_half_window_m_s=float(ccf_half_window_m_s), ) else: kw_h = {} kw_ccf = { **kw_h, "min_good_pixels": int(min_good_pixels), "zb": float(zb), } if return_ccf: all_rvs, all_rv_errs, all_wl, all_ccf, v_grid, all_n_good = process_all_orders_rvs_numba( wave_2d, spec_2d, spec_err_2d, dq_2d, do_not_use, template_ln, template_flux, window_size_um, order_indices, n_chunks_per_order, chunk_start, vm, vx, vs, return_ccf=True, numba_threads=nthr, **kw_ccf, ) return ( all_rvs, all_rv_errs, all_wl, all_ccf, v_grid, all_n_good, n_chunks_per_order, chunk_start, order_indices, ) all_rvs, all_rv_errs, all_wl = process_all_orders_rvs_numba( wave_2d, spec_2d, spec_err_2d, dq_2d, do_not_use, template_ln, template_flux, window_size_um, order_indices, n_chunks_per_order, chunk_start, vm, vx, vs, return_ccf=False, numba_threads=nthr, **kw_ccf, ) return all_rvs, all_rv_errs, all_wl, n_chunks_per_order, chunk_start
# ============================================================================= # Parallel CCF preview slot fits and Plotly / RVCCF preview payload assembly # =============================================================================
[docs] def _ccf_preview_finalize_n_workers(n_slots: int) -> int: """ Worker count for parallel Gaussian + refine in :func:`finalize_ccf_preview_dict`. Set ``HISPEC_DRP_CCF_PREVIEW_SLOT_THREADS`` to a positive int to cap workers; ``1`` forces sequential (legacy behavior). Unset or invalid: ``min(n_slots, cpu_count)``. """ raw = os.environ.get("HISPEC_DRP_CCF_PREVIEW_SLOT_THREADS", "").strip() if raw: try: n = int(raw) except ValueError: n = 0 if n < 1: return max(1, min(n_slots, os.cpu_count() or 4)) return max(1, min(n, n_slots)) return max(1, min(n_slots, os.cpu_count() or 4))
[docs] def _fit_ccf_preview_slot_worker( sl: dict, vs: float, *, ccf_line_mask_stored_negated: bool | None = None, line_mask_line_window_by_line: bool | None = None, line_mask_gaussian_seed_mean_m_s: float | None = None, ccf_bisector_config: CCFBisectorConfig | None = None, ) -> tuple[dict, dict | None]: """ One slot: :func:`fit_ccf_rv` with :data:`CCF_PREVIEW_SLOT_FIT_CONFIG`, then bisector RV for pipeline/preview metadata (:func:`_refine_ccf_rv_bisector_after_gaussian_fit`). Thread-safe (no shared mutable state). """ wl = sl.get("wl_lo", np.nan) if not np.isfinite(wl): wl = sl.get("wl_hi", np.nan) vsp = dv_per_pixel_m_s(float(wl)) ce = sl.get("ccf_err") ccf_err_arg = np.asarray(ce, np.float64) if ce is not None else None y_slot = np.asarray(sl["ccf"], np.float64) v_slot = np.asarray(sl["v"], np.float64) rv, rv_err, params, diag = fit_ccf_rv( v_slot, y_slot, vs, return_params=True, vel_span_m_s_per_pixel=vsp if np.isfinite(vsp) else None, ccf_err=ccf_err_arg, config=CCF_PREVIEW_SLOT_FIT_CONFIG, ccf_line_mask_stored_negated=ccf_line_mask_stored_negated, line_mask_line_window_by_line=line_mask_line_window_by_line, gaussian_seed_mean_m_s=line_mask_gaussian_seed_mean_m_s, ) gaussian_fit = { "rv": rv, "rv_err": rv_err, "params": params, "diagnostics": diag, } bisector_fit: dict | None = None if bool(diag.get("fit_ok")) and np.isfinite(rv): rv_bi, err_bi, bmeta = _refine_ccf_rv_bisector_after_gaussian_fit( v_slot, y_slot, vs, ccf_err=ccf_err_arg, config=ccf_bisector_config, gaussian_seed_mean_m_s=float(rv), ) if rv_bi is not None and math.isfinite(float(rv_bi)): bisector_fit = { "rv": float(rv_bi), "rv_err": ( float(err_bi) if err_bi is not None and math.isfinite(float(err_bi)) and float(err_bi) > 0 else float("nan") ), "diagnostics": bmeta if isinstance(bmeta, dict) else {}, } return gaussian_fit, bisector_fit
[docs] def _fit_ccf_preview_slots_line_mask_numba( slots: list[dict], v_step: float, *, line_mask_gaussian_seed_mean_m_s: float | None = None, config: CCFFitConfig | None = None, ) -> list[tuple[dict, dict | None]]: """ Batch Gaussian fits for mask-line preview slots (same Numba path as RVCCF). Avoids calling :func:`fit_ccf_rv_rows_numba` from multiple threads inside :func:`finalize_ccf_preview_dict` (Numba workqueue is not thread-safe). """ if not slots: return [] cfg = config or CCF_PREVIEW_SLOT_FIT_CONFIG v_slot = np.asarray(slots[0]["v"], dtype=np.float64).ravel() rows = np.vstack([np.asarray(sl["ccf"], dtype=np.float64).ravel() for sl in slots]) if rows.shape[1] != v_slot.size: raise ValueError("preview slots must share the same velocity grid") err_rows: np.ndarray | None = None err_list: list[np.ndarray] = [] for sl in slots: ce = sl.get("ccf_err") if ce is None: err_list = [] break err_list.append(np.asarray(ce, dtype=np.float64).ravel()) if err_list and len(err_list) == len(slots): err_rows = np.vstack(err_list) rv_arr, err_arr, ok_arr = fit_ccf_rv_rows_numba( v_slot, rows, ccf_err_rows=err_rows, gaussian_seed_mean_m_s=line_mask_gaussian_seed_mean_m_s, pass1_half_width_m_s=float(cfg.pass1_half_width_km_s) * 1000.0, pass2_half_width_m_s=float(cfg.pass2_half_width_km_s) * 1000.0, initial_stddev_m_s=float(cfg.initial_stddev_km_s) * 1000.0, levmar_maxiter=int(cfg.levmar_maxiter), min_points=int(cfg.min_points), max_cores=None, ) results: list[tuple[dict, dict | None]] = [] for i, sl in enumerate(slots): fit_ok = int(ok_arr[i]) == 1 rv_ms = float(rv_arr[i]) if fit_ok else float("nan") rv_err_ms = float(err_arr[i]) if fit_ok else float("nan") y_slot = rows[i] params, diag = _gaussian_preview_params_from_peak_up_ccf( v_slot, y_slot, rv_ms, rv_err_ms, fit_ok=fit_ok, config=cfg, gaussian_seed_mean_m_s=line_mask_gaussian_seed_mean_m_s, ) gaussian_fit = { "rv": rv_ms, "rv_err": rv_err_ms, "params": params, "diagnostics": diag, } bisector_fit: dict | None = None if fit_ok and np.isfinite(rv_ms): ce = sl.get("ccf_err") ccf_err_arg = np.asarray(ce, np.float64) if ce is not None else None rv_bi, err_bi, bmeta = _refine_ccf_rv_bisector_after_gaussian_fit( v_slot, y_slot, float(v_step), ccf_err=ccf_err_arg, gaussian_seed_mean_m_s=float(rv_ms), ) if rv_bi is not None and math.isfinite(float(rv_bi)): bisector_fit = { "rv": float(rv_bi), "rv_err": ( float(err_bi) if err_bi is not None and math.isfinite(float(err_bi)) and float(err_bi) > 0 else float("nan") ), "diagnostics": bmeta if isinstance(bmeta, dict) else {}, } results.append((gaussian_fit, bisector_fit)) return results
[docs] def finalize_ccf_preview_dict( order_slots: list[dict], all_ccf_rows: list[np.ndarray], v_grid: np.ndarray, v_min: float, v_max: float, v_step: float, all_ccf_err_rows: list[np.ndarray] | None = None, *, ccf_line_mask_stored_negated: bool | None = None, line_mask_line_window_by_line: bool | None = None, line_mask_gaussian_seed_mean_m_s: float | None = None, ) -> dict: """ Build the ``_ccf_preview_by_fiber`` structure from per-order CCF 2-D arrays. ``order_slots`` entries are typically one slot per line-mask chunk (or one per echelle order when a row is a single chunk); this prepends the global mean slot (mean over all stacked chunk rows in ``all_ccf_rows``). When ``all_ccf_err_rows`` is provided (one stacked array per order, aligned with ``all_ccf_rows``), the **mean** slot gets ``ccf_err`` = standard error of the column-wise mean CCF (``sqrt(sum σ²)/n``, not ``sqrt(mean(σ²))``) and :func:`fit_ccf_rv` uses them as inverse-variance weights. Parameters ---------- ccf_line_mask_stored_negated : bool or None, optional When not ``None``, forwarded to each slot’s :func:`fit_ccf_rv` call and copied to the returned dict as ``"ccf_line_mask_stored_negated"`` (mask-line preview only). line_mask_line_window_by_line : bool or None, optional Forwarded to :func:`fit_ccf_rv` (see :func:`_line_mask_ccf_fit_free_baseline_requested`). line_mask_gaussian_seed_mean_m_s : float or None, optional When set (typically ``ccf_input_velocity`` / grid center), passed to :func:`fit_ccf_rv` as ``gaussian_seed_mean_m_s`` for mask-line stored CCFs so the discrete peak seed is taken near the search center instead of a global maximum on a nearly flat curve. """ if not all_ccf_rows: out_empty: dict = { "v_step": float(v_step), "v_min": float(v_min), "v_max": float(v_max), "slots": [], } if ccf_line_mask_stored_negated is not None: out_empty["ccf_line_mask_stored_negated"] = bool(ccf_line_mask_stored_negated) return out_empty stacked = np.vstack(all_ccf_rows) combined = _nanmean_axis0_ignore_empty_columns(stacked) combined_err: np.ndarray | None = None if ( all_ccf_err_rows is not None and len(all_ccf_err_rows) == len(order_slots) and all(r.size > 0 for r in all_ccf_err_rows) ): stacked_e = np.vstack(all_ccf_err_rows) combined_err = _nan_stderr_of_mean_axis0(stacked_e, stacked) ng_mean = ( max(1, int(np.sum([max(1, int(s.get("n_good", 1))) for s in order_slots]))) if order_slots else 1 ) mean_slot = { "kind": "mean", "order": None, "v": np.asarray(v_grid, dtype=np.float64), "ccf": np.asarray(combined, dtype=np.float64), "wl_lo": float("nan"), "wl_hi": float("nan"), "n_good": ng_mean, } if combined_err is not None: mean_slot["ccf_err"] = np.asarray(combined_err, dtype=np.float64) slots = [mean_slot] + order_slots vs = float(v_step) if bool(ccf_line_mask_stored_negated): logger.info( "CCF preview: finalize_ccf_preview_dict fitting Gaussians n_slots=%d " "(mask-line batch Numba)", len(slots), ) results = _fit_ccf_preview_slots_line_mask_numba( slots, vs, line_mask_gaussian_seed_mean_m_s=line_mask_gaussian_seed_mean_m_s, config=CCF_PREVIEW_SLOT_FIT_CONFIG, ) else: n_workers = _ccf_preview_finalize_n_workers(len(slots)) logger.info( "CCF preview: finalize_ccf_preview_dict fitting Gaussians n_slots=%d n_workers=%d " "(mean + orders)", len(slots), n_workers, ) def _run_slot(s: dict) -> tuple[dict, dict | None]: return _fit_ccf_preview_slot_worker( s, vs, ccf_line_mask_stored_negated=ccf_line_mask_stored_negated, line_mask_line_window_by_line=line_mask_line_window_by_line, line_mask_gaussian_seed_mean_m_s=line_mask_gaussian_seed_mean_m_s, ) if n_workers <= 1: results = [_run_slot(sl) for sl in slots] else: with ThreadPoolExecutor(max_workers=n_workers) as ex: results = list(ex.map(_run_slot, slots)) for sl, (gaussian_fit, bisector_fit) in zip(slots, results): sl["gaussian_fit"] = gaussian_fit if bisector_fit is not None: sl["bisector_fit"] = bisector_fit logger.info( "CCF preview: finalize_ccf_preview_dict Gaussian + bisector fits done n_slots=%d", len(slots), ) out: dict = { "v_step": float(v_step), "v_min": float(v_min), "v_max": float(v_max), "slots": slots, } if ccf_line_mask_stored_negated is not None: out["ccf_line_mask_stored_negated"] = bool(ccf_line_mask_stored_negated) if ( line_mask_gaussian_seed_mean_m_s is not None and math.isfinite(float(line_mask_gaussian_seed_mean_m_s)) ): out["line_mask_gaussian_seed_mean_m_s"] = float(line_mask_gaussian_seed_mean_m_s) return out
[docs] def build_ccf_preview_dict( kind: Literal["numba_flat", "spectra_orders"], order_tasks: list[tuple[int, int]], v_min: float, v_max: float, v_step: float, *, order_indices: np.ndarray | None = None, n_chunks_per_order: np.ndarray | None = None, chunk_start: np.ndarray | None = None, all_ccf: np.ndarray | None = None, v_grid: np.ndarray | None = None, wave_2d: np.ndarray | None = None, wave: np.ndarray | None = None, spec: np.ndarray | None = None, err: np.ndarray | None = None, dq: np.ndarray | None = None, do_not_use: int | None = None, template_ln: np.ndarray | None = None, template_flux: np.ndarray | None = None, window_size_um: float | None = None, ) -> dict | None: """ Build the stellar-RV CCF preview JSON-like structure for Plotly (per-order slots, mean CCF, Gaussian). Parameters ---------- kind : {'numba_flat', 'spectra_orders'} Which construction path to use: * ``numba_flat`` — consume flattened Numba outputs from :func:`process_orders_rvs_numba_parallel` with ``return_ccf=True`` (``all_ccf``, ``chunk_start``, ``n_chunks_per_order``, ``order_indices``, ``v_grid``, ``wave_2d``). * ``spectra_orders`` — run :func:`rv_per_chunks` per order in pure Python (slower; useful when debugging or avoiding the Numba stack). order_tasks : list of tuple ``(order_row_index, echelle_order_number)`` for each order included in the preview. v_min, v_max, v_step : float CCF velocity grid bounds and step (m/s) used for logging and passed through to :func:`finalize_ccf_preview_dict` for axis metadata and Gaussian reference curves. order_indices, n_chunks_per_order, chunk_start : ndarray, optional Required for ``kind='numba_flat'``. Layout matches :func:`process_orders_rvs_numba_parallel`: ``chunk_start`` indexes into the flattened ``all_ccf`` rows per order block. all_ccf : ndarray, optional 2-D array of CCF rows (chunks × velocity), required for ``numba_flat``. v_grid : ndarray, optional 1-D velocity samples (m/s), required for ``numba_flat``. wave_2d : ndarray, optional Shape ``(n_orders, n_pix)`` wavelength grid (µm); required for ``numba_flat`` to annotate wavelength span per order slot. wave, spec, err, dq : ndarray, optional Required for ``spectra_orders``: 2-D extracted-order arrays (same axis 0 as ``order_tasks`` row indices). do_not_use : int or None, optional DQ bitmask; pixels with ``(dq & do_not_use) != 0`` are treated as bad for masking. template_ln, template_flux : ndarray, optional Full template in ln(micron) and flux for ``spectra_orders``. window_size_um : float or None, optional Chunk width (µm) for :func:`rv_per_chunks` in ``spectra_orders`` mode. Returns ------- dict or None Structure consumed by :mod:`hispecdrp.primitives.stellar_rv.previews.stellar_rv_preview` (order slots + aggregated rows + fit metadata), or ``None`` if there is nothing to plot (no valid orders, empty CCF, or length mismatch between orders). Raises ------ ValueError If required arguments for the selected ``kind`` are missing, or ``kind`` is unknown. """ if kind == "numba_flat": if ( order_indices is None or n_chunks_per_order is None or chunk_start is None or all_ccf is None or v_grid is None or wave_2d is None ): raise ValueError( "build_ccf_preview_dict(kind='numba_flat') requires order_indices, " "n_chunks_per_order, chunk_start, all_ccf, v_grid, wave_2d" ) if not order_tasks or len(v_grid) == 0: return None order_slots: list[dict] = [] all_rows: list[np.ndarray] = [] for idx in range(len(order_tasks)): oi = int(order_indices[idx]) order_num = int(order_tasks[idx][1]) start = int(chunk_start[idx]) nch = int(n_chunks_per_order[idx]) block = all_ccf[start : start + nch] if block.size == 0: continue ccf_m = _nanmean_axis0_ignore_empty_columns(np.asarray(block, dtype=np.float64)) w = wave_2d[oi] wl_lo, wl_hi = float(np.nanmin(w)), float(np.nanmax(w)) order_slots.append( { "kind": "order", "order": order_num, "v": np.asarray(v_grid, dtype=np.float64), "ccf": np.asarray(ccf_m, dtype=np.float64), "wl_lo": wl_lo, "wl_hi": wl_hi, } ) all_rows.append(block) if not order_slots: return None logger.info( "CCF preview: build_ccf_preview_dict numba_flat n_orders=%d (mean CCF + finalize)", len(order_slots), ) return finalize_ccf_preview_dict(order_slots, all_rows, v_grid, v_min, v_max, v_step) if kind == "spectra_orders": if ( wave is None or spec is None or err is None or dq is None or do_not_use is None or template_ln is None or template_flux is None or window_size_um is None ): raise ValueError( "build_ccf_preview_dict(kind='spectra_orders') requires wave, spec, err, dq, " "do_not_use, template_ln, template_flux, window_size_um" ) if not order_tasks: return None logger.info( "CCF preview: build_ccf_preview_dict spectra_orders n_order_tasks=%d " "window_um=%.4f v_grid=[%.0f, %.0f] m/s step=%.1f", len(order_tasks), window_size_um, v_min, v_max, v_step, ) order_slots_so: list[dict] = [] all_rows_so: list[np.ndarray] = [] v_grid_ref = None for oi, order in order_tasks: w = np.asarray(wave[oi], dtype=np.float64) s = np.asarray(spec[oi], dtype=np.float64).copy() e = np.asarray(err[oi] if err.ndim >= 2 else err, dtype=np.float64) d = np.asarray(dq[oi] if dq.ndim >= 2 else dq, dtype=np.uint32) mask = (d & do_not_use) != 0 w_min, w_max = np.nanmin(w), np.nanmax(w) ln_min, ln_max = np.log(w_min), np.log(w_max) in_range = (template_ln >= ln_min - 0.01) & (template_ln <= ln_max + 0.01) if np.sum(in_range) < 20: continue t_ln = template_ln[in_range] t_flux = template_flux[in_range] _rvs, _rv_errs, _centers, v_grid_o, ccf_2d = rv_per_chunks( w, s, e, mask, t_ln, t_flux, window_size_um, v_min=v_min, v_max=v_max, v_step=v_step, return_ccf=True, ) if v_grid_ref is None: v_grid_ref = v_grid_o elif v_grid_ref.shape != v_grid_o.shape or not np.allclose(v_grid_ref, v_grid_o): continue ccf_m = _nanmean_axis0_ignore_empty_columns(np.asarray(ccf_2d, dtype=np.float64)) order_slots_so.append( { "kind": "order", "order": int(order), "v": np.asarray(v_grid_o, dtype=np.float64), "ccf": np.asarray(ccf_m, dtype=np.float64), "wl_lo": float(np.nanmin(w)), "wl_hi": float(np.nanmax(w)), } ) all_rows_so.append(ccf_2d) if not order_slots_so or v_grid_ref is None: logger.info( "CCF preview: build_ccf_preview_dict spectra_orders no valid orders after CCF pass" ) return None logger.info( "CCF preview: build_ccf_preview_dict spectra_orders built %d order slots; finalize", len(order_slots_so), ) return finalize_ccf_preview_dict( order_slots_so, all_rows_so, v_grid_ref, v_min, v_max, v_step ) raise ValueError(f"unknown build_ccf_preview_dict kind: {kind!r}")
# ============================================================================= # Continuum normalization (optional pre-step before CCF on extracted orders) # =============================================================================
[docs] def continuum_normalize( flux: np.ndarray, wavelength: np.ndarray | None = None, lowpass_window: int | None = None, poly_order: int | None = None, ) -> np.ndarray: """ Divide flux by an estimated continuum (median filter and/or polynomial). Used optionally before CCF in :func:`process_one_order_rvs` so line depths are less sensitive to slow spectral slope. Parameters ---------- flux : np.ndarray 1-D flux. wavelength : np.ndarray or None, optional Abscissa for polynomial continuum; if None, pixel index is used. lowpass_window : int or None, optional Odd median-filter window; even values are incremented. None skips filtering. poly_order : int or None, optional If set, fit continuum as a polynomial of this order (after median step if any). Returns ------- np.ndarray ``flux / continuum``, same shape as ``flux``. Notes ----- If both ``lowpass_window`` and ``poly_order`` are None, returns ``flux`` unchanged. """ flux = np.asarray(flux, dtype=np.float64) n = len(flux) if n == 0 or (lowpass_window is None and poly_order is None): return flux x = np.asarray(wavelength, dtype=np.float64) if wavelength is not None else np.arange(n, dtype=np.float64) if len(x) != n: x = np.arange(n, dtype=np.float64) continuum = np.full_like(flux, np.nan) if lowpass_window is not None and lowpass_window > 0: w = int(lowpass_window) if w % 2 == 0: w += 1 w = min(w, n) if w >= 3: continuum = median_filter(flux, size=w, mode="nearest") else: continuum = np.where(np.isfinite(flux), flux, np.nan) else: continuum = np.where(np.isfinite(flux), flux, np.nan) if poly_order is not None and poly_order >= 0: ok = np.isfinite(x) & np.isfinite(continuum) & (continuum > 0) if np.sum(ok) > max(poly_order + 1, 5): try: p = np.polyfit(x[ok], continuum[ok], poly_order) continuum = np.polyval(p, x) except Exception: pass continuum = np.maximum(continuum, 1e-30) return np.where(np.isfinite(flux) & np.isfinite(continuum), flux / continuum, flux)
# ============================================================================= # Masked log-λ template CCF (single order or chunk): weighted covariance + Gaussian fit # =============================================================================
[docs] def _ln_lam(wave: np.ndarray) -> np.ndarray: """Natural log of wavelength (micron → log micron). Internal helper.""" return np.log(np.asarray(wave, dtype=np.float64))
[docs] def _ccf_weighted_covariance_scan( ln_lam: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, good: np.ndarray, template_ln: np.ndarray, template_flux: np.ndarray, v_grid: np.ndarray, zb: float = 0.0, ) -> np.ndarray: """Python CCF(v); same statistic as ``_ccf_chunk_ccf_numba`` (fallback when Numba off).""" ccf = np.zeros_like(v_grid, dtype=np.float64) zb1 = 1.0 + float(zb) if zb1 <= 0.0: zb1 = 1.0 for i, v in enumerate(v_grid): delta_ln = math.log((1.0 + float(v) / C_M_S) / zb1) t_at_data = np.interp( ln_lam, template_ln + delta_ln, template_flux, left=0.0, right=0.0, ) use = good & np.isfinite(t_at_data) & (t_at_data != 0) if np.sum(use) < 5: ccf[i] = np.nan continue d = spec[use] t = t_at_data[use] w = 1.0 / np.maximum(spec_err[use] ** 2, 1e-30) d_norm = d - np.average(d, weights=w) t_norm = t - np.average(t, weights=w) ccf[i] = np.average(d_norm * t_norm, weights=w) return ccf
[docs] def _masked_ccf_rv_core( wave: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, mask: np.ndarray, template_ln: np.ndarray, template_flux: np.ndarray, v_min: float, v_max: float, v_step: float, *, diagnostics: bool, v_grid: np.ndarray | None = None, zb: float = 0.0, min_good_pixels: int = 10, ) -> tuple[float, float, np.ndarray, np.ndarray, dict | None]: """ Single CCF build + fit; optionally build diagnostics dict (no duplicate CCF work). Returns ------- rv, rv_err, v_grid, ccf, diagnostics_or_none """ good = ~mask & np.isfinite(spec) & np.isfinite(spec_err) & (spec_err > 0) n_good = int(np.sum(good)) wl_min = float(np.nanmin(wave)) wl_max = float(np.nanmax(wave)) spec_mean = float(np.nanmean(spec[good])) if n_good > 0 else np.nan spec_std = float(np.nanstd(spec[good])) if n_good > 1 else 0.0 empty_diag = { "ccf_max": np.nan, "ccf_min": np.nan, "n_good": n_good, "n_use_at_peak": 0, "spec_mean": spec_mean, "spec_std": spec_std, "template_mean_at_peak": np.nan, "template_std_at_peak": np.nan, "wl_min": wl_min, "wl_max": wl_max, } if v_grid is not None: v_grid = np.asarray(v_grid, dtype=np.float64).ravel() else: v_grid = _make_velocity_grid(v_min, v_max, v_step) mg = int(min_good_pixels) if n_good < mg: nan_ccf = np.full_like(v_grid, np.nan) if diagnostics: return np.nan, np.nan, v_grid, nan_ccf, empty_diag return np.nan, np.nan, v_grid, nan_ccf, None ln_lam = _ln_lam(wave) ccf = np.full(len(v_grid), np.nan, dtype=np.float64) v_step_fit = effective_ccf_v_step_for_fit(v_grid) if ( len(v_grid) >= 2 and np.allclose(np.diff(v_grid), v_grid[1] - v_grid[0], rtol=1e-5, atol=1e-3) ): _ccf_chunk_ccf_numba( ln_lam, spec, spec_err, good, template_ln, template_flux, float(v_grid[0]), float(v_grid[-1]), float(v_grid[1] - v_grid[0]), ccf, mg, float(zb), ) else: ccf[:] = _ccf_weighted_covariance_scan( ln_lam, spec, spec_err, good, template_ln, template_flux, v_grid, zb=float(zb), ) if not np.any(np.isfinite(ccf)): if diagnostics: return np.nan, np.nan, v_grid, ccf, empty_diag return np.nan, np.nan, v_grid, ccf, None rv, rv_err = _ccf_rv_from_ccf( v_grid, ccf, v_step_fit, n_good, min_good_pixels=mg, ) diag_out: dict | None = None if diagnostics: ccf_max = float(np.nanmax(ccf)) ccf_min = float(np.nanmin(ccf)) zb1 = 1.0 + float(zb) if zb1 <= 0.0: zb1 = 1.0 delta_ln_peak = math.log((1.0 + float(rv) / C_M_S) / zb1) template_ln_shifted = template_ln + delta_ln_peak t_at_data = np.interp( ln_lam, template_ln_shifted, template_flux, left=0.0, right=0.0 ) use_peak = good & np.isfinite(t_at_data) & (t_at_data != 0) n_use_at_peak = int(np.sum(use_peak)) t_mean = float(np.mean(t_at_data[use_peak])) if n_use_at_peak > 0 else np.nan t_std = float(np.std(t_at_data[use_peak])) if n_use_at_peak > 1 else 0.0 diag_out = { "ccf_max": ccf_max, "ccf_min": ccf_min, "n_good": n_good, "n_use_at_peak": n_use_at_peak, "spec_mean": spec_mean, "spec_std": spec_std, "template_mean_at_peak": t_mean, "template_std_at_peak": t_std, "wl_min": wl_min, "wl_max": wl_max, } return rv, rv_err, v_grid, ccf, diag_out
[docs] def masked_ccf_rv( wave: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, mask: np.ndarray, template_ln: np.ndarray, template_flux: np.ndarray, v_min: float = -500000.0, v_max: float = 500000.0, v_step: float = 500.0, *, v_grid: np.ndarray | None = None, zb: float = 0.0, min_good_pixels: int = 10, return_ccf: bool = False, diagnostics: bool = False, ) -> ( tuple[float, float] | tuple[float, float, np.ndarray, np.ndarray] | tuple[float, float, dict] | tuple[float, float, np.ndarray, np.ndarray, dict] ): """ Radial velocity from a single masked spectrum via log-λ CCF and Gaussian peak fit. Builds a weighted covariance CCF on a velocity grid, then calls :func:`fit_ccf_rv` (sub-grid RV); on failure uses the grid peak and a HWHM-based error. Parameters ---------- wave : np.ndarray Wavelength per pixel, micron. spec, spec_err : np.ndarray Flux and uncertainty. mask : np.ndarray Boolean bad-pixel mask; **``True`` excludes** the pixel from the weighted CCF. template_ln, template_flux : np.ndarray Stellar template sampled on **natural log wavelength** (ln µm) and flux, covering the observed wavelength interval. v_min, v_max, v_step : float, optional Uniform CCF velocity range and step (m/s) when ``v_grid`` is not passed. Ignored if ``v_grid`` is given. v_grid : np.ndarray or None, optional Explicit velocity samples (m/s), e.g. from :func:`build_centered_uniform_velocity_grid`. When passed, ``v_min`` / ``v_max`` / ``v_step`` are not used to build the grid. zb : float, optional Barycentric factor in the template :math:`\\ln\\lambda` shift (see :func:`_ccf_chunk_ccf_numba`). min_good_pixels : int, optional Minimum good pixels required before building the CCF and fitting. Returns ------- tuple * Default: ``(rv, rv_err)`` with RV and uncertainty (m/s). * ``return_ccf=True``: ``(rv, rv_err, v_grid, ccf)``. * ``diagnostics=True``: ``(rv, rv_err, diagnostics)``. * Both flags: ``(rv, rv_err, v_grid, ccf, diagnostics)``. Notes ----- Calls :func:`fit_ccf_rv` for sub-grid Gaussian RV when the weighted CCF is valid; otherwise falls back to the discrete peak with a HWHM-style error estimate. See Also -------- rv_per_chunks : Per-chunk CCFs along an order. """ rv, rv_err, vg, ccf, diag = _masked_ccf_rv_core( wave, spec, spec_err, mask, template_ln, template_flux, v_min, v_max, v_step, diagnostics=diagnostics, v_grid=v_grid, zb=float(zb), min_good_pixels=int(min_good_pixels), ) if return_ccf and diagnostics: assert diag is not None return rv, rv_err, vg, ccf, diag if return_ccf: return rv, rv_err, vg, ccf if diagnostics: assert diag is not None return rv, rv_err, diag return rv, rv_err
# ============================================================================= # Split spectrum into wavelength chunks; each chunk → masked_ccf_rv # =============================================================================
[docs] def rv_per_chunks( wave: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, mask: np.ndarray, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, v_min: float = -500000.0, v_max: float = 500000.0, v_step: float = 500.0, *, return_ccf: bool = False, ) -> ( tuple[np.ndarray, np.ndarray, np.ndarray] | tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] ): """ Split one echelle spectrum into wavelength chunks; one RV per chunk. Each chunk with at least 20 finite pixels uses :func:`_masked_ccf_rv_core` once (Numba CCF when available). Chunks with fewer valid pixels are left as NaN RVs. Parameters ---------- wave : np.ndarray 1-D wavelength samples (µm), same length as ``spec``. spec, spec_err : np.ndarray Flux and per-pixel uncertainty. mask : np.ndarray Boolean; **``True`` excludes** pixels from the CCF (same convention as :func:`masked_ccf_rv`). template_ln, template_flux : np.ndarray Template on ln(µm) and flux, covering the order’s wavelength span. window_size_um : float Target chunk width (µm); chunk count is :func:`ccf_order_n_chunks_for_span` applied to the order wavelength span. v_min, v_max, v_step : float, optional Uniform velocity grid (m/s) for the CCF inside each chunk. return_ccf : bool, optional If ``True``, also return ``v_grid`` and a 2-D array ``ccf_2d`` with shape ``(n_chunk, n_vel)`` (NaN rows where a chunk did not run). Returns ------- rvs, rv_errs, chunk_centers : np.ndarray Per-chunk RV (m/s), uncertainty (m/s), and chunk center wavelength (µm). v_grid, ccf_2d : np.ndarray, optional Returned only when ``return_ccf=True``: shared velocity axis and stacked CCF rows. See Also -------- masked_ccf_rv : Single-spectrum masked CCF on one segment. """ w_min, w_max = np.nanmin(wave), np.nanmax(wave) span = float(w_max - w_min) n_chunk = ccf_order_n_chunks_for_span(span, float(window_size_um)) rvs = np.full(n_chunk, np.nan, dtype=np.float64) rv_errs = np.full(n_chunk, np.nan, dtype=np.float64) v_grid = _make_velocity_grid(v_min, v_max, v_step) ccf_2d = ( np.full((n_chunk, len(v_grid)), np.nan, dtype=np.float64) if return_ccf else None ) chunk_centers = np.full(n_chunk, np.nan, dtype=np.float64) for k in range(n_chunk): lam_lo = w_min + k * span / n_chunk lam_hi = w_min + (k + 1) * span / n_chunk if k == n_chunk - 1: in_chunk = (wave >= lam_lo) & (wave <= lam_hi) else: in_chunk = (wave >= lam_lo) & (wave < lam_hi) chunk_centers[k] = 0.5 * (lam_lo + lam_hi) if np.sum(in_chunk) < 20: continue rv, rv_err, vg, ccf, _ = _masked_ccf_rv_core( wave[in_chunk], spec[in_chunk], spec_err[in_chunk], mask[in_chunk], template_ln, template_flux, v_min, v_max, v_step, diagnostics=False, ) rvs[k] = rv rv_errs[k] = rv_err if return_ccf and ccf_2d is not None and vg.shape == v_grid.shape and np.allclose(vg, v_grid): ccf_2d[k, :] = ccf if return_ccf: assert ccf_2d is not None return rvs, rv_errs, chunk_centers, v_grid, ccf_2d return rvs, rv_errs, chunk_centers
# ============================================================================= # Single-order helper + multi-chunk CCF export (preview / diagnostics) # =============================================================================
[docs] def process_one_order_rvs( wave: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, dq: np.ndarray, do_not_use: int, template_ln: np.ndarray, template_flux: np.ndarray, window_size_um: float, do_continuum_normalize: bool = False, continuum_lowpass_window: int | None = None, continuum_poly_order: int | None = None, *, return_ccf: bool = False, ccf_v_min: float | None = None, ccf_v_max: float | None = None, ccf_v_step: float | None = None, ccf_center_m_s: float | None = None, ccf_half_window_m_s: float = 20000.0, ) -> ( tuple[np.ndarray, np.ndarray, np.ndarray] | tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray] ): """ One echelle order: clip template, optional continuum norm, chunk RVs. Serial-friendly (picklable) path used when not using the Numba multi-order driver. Returns empty arrays if the template has fewer than 20 points in the order wavelength range. When ``ccf_center_m_s`` is set, delegates to :func:`process_orders_rvs_numba_parallel` (centered uniform window). Parameters ---------- wave, spec, spec_err : np.ndarray 1-D wavelength (micron), flux, uncertainty. dq : np.ndarray, uint32 Data quality; pixels with ``(dq & do_not_use) != 0`` are masked. do_not_use : int DQ bitmask for bad pixels. template_ln, template_flux : np.ndarray Full-template arrays (log micron, flux). window_size_um : float Wavelength chunk width (micron). do_continuum_normalize : bool, optional If True and a continuum option is set, normalize flux before CCF. continuum_lowpass_window, continuum_poly_order : int or None, optional Passed to :func:`continuum_normalize`. return_ccf : bool, optional If True, also return ``v_grid`` and per-chunk CCF ``ccf_2d`` (uses ``ccf_v_min`` / ``ccf_v_max`` / ``ccf_v_step`` or defaults ``_V_*``). ccf_v_min, ccf_v_max, ccf_v_step : float or None, optional Uniform velocity grid (m/s). When ``ccf_center_m_s`` is set, ``ccf_v_step`` samples the centered window; otherwise they define the sole grid for :func:`rv_per_chunks`. Defaults use module ``V_MIN_DEFAULT_M_S``, ``V_MAX_DEFAULT_M_S``, ``V_STEP_DEFAULT_M_S``. ccf_center_m_s : float or None, optional When **finite**, delegates to :func:`process_orders_rvs_numba_parallel` on this single order with a uniform window centered here. When ``None``, uses the uniform broad grid only (via ``rv_per_chunks``). ccf_half_window_m_s : float, optional Half-width (m/s) of the centered uniform window when ``ccf_center_m_s`` is set. Returns ------- rvs : np.ndarray Per-chunk RV (m/s). rv_errs : np.ndarray Per-chunk uncertainties (m/s). chunk_centers : np.ndarray Chunk center wavelengths (micron). v_grid, ccf_2d : np.ndarray, optional Returned only when ``return_ccf`` is True. See Also -------- process_orders_rvs_numba_parallel : Faster path for many orders at once. """ w = np.asarray(wave, dtype=np.float64) s = np.asarray(spec, dtype=np.float64).copy() e = np.asarray(spec_err, dtype=np.float64) mask = (np.asarray(dq, dtype=np.uint32) & do_not_use) != 0 if do_continuum_normalize and (continuum_lowpass_window is not None or continuum_poly_order is not None): s = continuum_normalize( s, wavelength=w, lowpass_window=continuum_lowpass_window, poly_order=continuum_poly_order, ) w_min, w_max = np.nanmin(w), np.nanmax(w) ln_min, ln_max = np.log(w_min), np.log(w_max) in_range = (template_ln >= ln_min - 0.01) & (template_ln <= ln_max + 0.01) if np.sum(in_range) < 20: empty3 = ( np.array([], dtype=np.float64), np.array([], dtype=np.float64), np.array([], dtype=np.float64), ) if return_ccf: vm = V_MIN_DEFAULT_M_S if ccf_v_min is None else ccf_v_min vx = V_MAX_DEFAULT_M_S if ccf_v_max is None else ccf_v_max vs = V_STEP_DEFAULT_M_S if ccf_v_step is None else ccf_v_step vg = _make_velocity_grid(vm, vx, vs) return empty3 + (vg, np.zeros((0, len(vg)), dtype=np.float64)) return empty3 t_ln = template_ln[in_range] t_flux = template_flux[in_range] vm = V_MIN_DEFAULT_M_S if ccf_v_min is None else ccf_v_min vx = V_MAX_DEFAULT_M_S if ccf_v_max is None else ccf_v_max vs = V_STEP_DEFAULT_M_S if ccf_v_step is None else ccf_v_step if ccf_center_m_s is not None: dq_1d = np.where(mask, np.uint32(do_not_use), np.uint32(0)) wave_2d = w.reshape(1, -1) spec_2d = s.reshape(1, -1) err_2d = e.reshape(1, -1) dq_2d = dq_1d.reshape(1, -1) out = process_orders_rvs_numba_parallel( wave_2d, spec_2d, err_2d, dq_2d, do_not_use, t_ln, t_flux, window_size_um, [(0, 0)], max_cores=1, return_ccf=return_ccf, ccf_v_min=vm, ccf_v_max=vx, ccf_v_step=vs, ccf_center_m_s=float(ccf_center_m_s), ccf_half_window_m_s=float(ccf_half_window_m_s), ) if return_ccf: arv, are, awl, accf, vg, ang, _nc, _cs, _oi = out return arv, are, awl, vg, accf arv, are, awl, _nc, _cs = out return arv, are, awl return rv_per_chunks( w, s, e, mask, t_ln, t_flux, window_size_um, v_min=vm, v_max=vx, v_step=vs, return_ccf=return_ccf, )
# ============================================================================= # Mask-shift line CCF (SPIROU .mas / KPF two-column) # =============================================================================
[docs] @njit(cache=True) def _linear_interp_sorted_1d(xq: float, x: np.ndarray, y: np.ndarray, n: int) -> float: """Linear interpolation on sorted ``x[:n]`` (ascending); clamps outside range.""" if n <= 0: return np.nan if xq <= x[0]: return float(y[0]) if xq >= x[n - 1]: return float(y[n - 1]) i = int(np.searchsorted(x, xq, side="right")) i0 = i - 1 i1 = i0 + 1 if i1 >= n: return float(y[n - 1]) x0 = float(x[i0]) x1 = float(x[i1]) if x1 <= x0: return float(y[i0]) t = (xq - x0) / (x1 - x0) return (1.0 - t) * float(y[i0]) + t * float(y[i1])
[docs] @njit(cache=True, inline="always") def _normalized_sinc(x: float) -> float: """``sin(πx)/(πx)`` with ``sinc(0)=1``.""" if x == 0.0: return 1.0 pix = math.pi * x return math.sin(pix) / pix
[docs] @njit(cache=True, inline="always") def _lanczos_kernel(x: float, a: float) -> float: """Lanczos-*a* kernel: ``sinc(x) sinc(x/a)`` for ``|x|<a``, else 0.""" ax = abs(x) if ax >= a: return 0.0 if ax == 0.0: return 1.0 return _normalized_sinc(x) * _normalized_sinc(x / a)
[docs] @njit(cache=True, inline="always") def _fractional_pixel_index(xq: float, x: np.ndarray, n: int) -> float: """ Continuous pixel index for ``xq`` on sorted abscissae ``x[:n]``. Linear in wavelength between neighboring samples (handles mildly irregular BSPEC WAVE spacing while applying the band-limited kernel in pixel index). """ j = int(np.searchsorted(x, xq, side="right")) - 1 if j < 0: j = 0 if j >= n - 1: j = n - 2 x0 = float(x[j]) x1 = float(x[j + 1]) dx = x1 - x0 if dx == 0.0: return float(j) return float(j) + (xq - x0) / dx
[docs] @njit(cache=True) def _poly_interp_sorted_1d( xq: float, x: np.ndarray, y: np.ndarray, n: int, order: int, ) -> float: """ Interpolate ``y`` at ``xq`` on sorted ``x[:n]`` (ascending). * ``order == 1`` — linear between bracketing samples (fast / robust). * ``order >= 2`` — **Lanczos-a** windowed-sinc in **pixel-index** space with ``a = order`` (science default ``a = 3``). Clamps outside ``[x[0], x[n-1]]``. Near edges the truncated kernel is renormalized. """ if n <= 0: return np.nan if n == 1: return float(y[0]) o = int(order) if o < 1: o = 1 if o > MAX_MASK_CCF_PIXEL_INTERP_ORDER: o = MAX_MASK_CCF_PIXEL_INTERP_ORDER if xq <= float(x[0]): return float(y[0]) if xq >= float(x[n - 1]): return float(y[n - 1]) if o == 1: j = int(np.searchsorted(x, xq, side="right")) - 1 if j < 0: j = 0 if j >= n - 1: j = n - 2 x0 = float(x[j]) x1 = float(x[j + 1]) dx = x1 - x0 if dx == 0.0: return float(y[j]) t = (xq - x0) / dx return (1.0 - t) * float(y[j]) + t * float(y[j + 1]) a = float(o) pf = _fractional_pixel_index(xq, x, n) i0 = int(math.floor(pf)) - o + 1 i1 = int(math.floor(pf)) + o if i0 < 0: i0 = 0 if i1 > n - 1: i1 = n - 1 acc = 0.0 wsum = 0.0 for i in range(i0, i1 + 1): w = _lanczos_kernel(pf - float(i), a) if w == 0.0: continue acc += w * float(y[i]) wsum += w if wsum == 0.0: j = int(math.floor(pf + 0.5)) if j < 0: j = 0 if j > n - 1: j = n - 1 return float(y[j]) return acc / wsum
# Minimum R and per-pixel samples for Doppler paint (template densification). _DEFAULT_DOPPLER_PAINT_RESOLUTION_FLOOR = 3.0e5 _DEFAULT_DOPPLER_PAINT_SAMPLES_PER_PIXEL = 8.0 _DEFAULT_DOPPLER_PAINT_RESOLUTION_CEILING = 1.0e7
[docs] def template_min_resolution_for_doppler_paint( wave_obs_um: np.ndarray, *, samples_per_pixel: float = _DEFAULT_DOPPLER_PAINT_SAMPLES_PER_PIXEL, resolution_floor: float = _DEFAULT_DOPPLER_PAINT_RESOLUTION_FLOOR, resolution_ceiling: float = _DEFAULT_DOPPLER_PAINT_RESOLUTION_CEILING, ) -> float: """ Minimum template resolving power ``R = lambda / dlambda`` for Doppler paint. Ensures at least ``samples_per_pixel`` rest-frame knots span one median observed-pixel width on ``wave_obs_um``. BT-Settl in the BSPEC band is often already ``R > 3e5`` but can still be **undersampled for cm/s Doppler paint** when only ~one native knot falls inside a BSPEC pixel (~500 m/s wide). Parameters ---------- wave_obs_um Observed wavelength grid (um), typically one echelle order from the instrument WAVE solution. May increase or decrease with pixel index. samples_per_pixel Target number of template samples per observed pixel (default ``8``). resolution_floor, resolution_ceiling Clamp the returned ``R`` to ``[floor, ceiling]``. Returns ------- float Resolving power to pass to :func:`prepare_template_for_doppler_paint` / ``simulate_rate_map._upsample_spectrum``. """ w = np.asarray(wave_obs_um, dtype=np.float64).ravel() if w.size < 2: return float(resolution_floor) dlam_pix = float(np.median(np.abs(np.diff(w)))) lam_mid = float(np.median(w)) if dlam_pix <= 0.0 or lam_mid <= 0.0 or not np.isfinite(dlam_pix): return float(resolution_floor) spp = float(samples_per_pixel) if spp < 1.0: spp = 1.0 dlam_target = dlam_pix / spp r_req = lam_mid / dlam_target return float(np.clip(r_req, float(resolution_floor), float(resolution_ceiling)))
[docs] def prepare_template_for_doppler_paint( wave_rest_um: np.ndarray, flux_rest: np.ndarray, wave_obs_um: np.ndarray, *, samples_per_pixel: float = _DEFAULT_DOPPLER_PAINT_SAMPLES_PER_PIXEL, resolution_floor: float = _DEFAULT_DOPPLER_PAINT_RESOLUTION_FLOOR, resolution_ceiling: float = _DEFAULT_DOPPLER_PAINT_RESOLUTION_CEILING, ) -> tuple[np.ndarray, np.ndarray]: """ Densify a rest-frame spectrum for :func:`doppler_paint_lanczos`. Inserts PCHIP knots only where local ``R`` falls below the value returned by :func:`template_min_resolution_for_doppler_paint` for ``wave_obs_um``. Native samples are preserved (see ``simulate_rate_map._upsample_spectrum``). Returns ------- wave_rest_um, flux_rest Float64 arrays, strictly ascending wavelength. """ from astropy import units as u from hispecdrp.simulations.simulate_rate_map import _upsample_spectrum w_rest = np.asarray(wave_rest_um, dtype=np.float64).ravel() f_rest = np.asarray(flux_rest, dtype=np.float64).ravel() if w_rest.size != f_rest.size: raise ValueError("wave_rest_um and flux_rest must have the same length") r_req = template_min_resolution_for_doppler_paint( wave_obs_um, samples_per_pixel=samples_per_pixel, resolution_floor=resolution_floor, resolution_ceiling=resolution_ceiling, ) wd, fd = _upsample_spectrum( w_rest * u.um, f_rest * u.dimensionless_unscaled, desired_sampling_resolution=float(r_req), ) return ( np.asarray(wd.value, dtype=np.float64).ravel(), np.asarray(fd.value, dtype=np.float64).ravel(), )
[docs] def doppler_paint_lanczos( wave_obs_um: np.ndarray, wave_rest_um: np.ndarray, flux_rest: np.ndarray, rv_m_s: float, *, zb: float = 0.0, order: int = 3, prepare_for_obs_grid: np.ndarray | None = None, prepare_samples_per_pixel: float = _DEFAULT_DOPPLER_PAINT_SAMPLES_PER_PIXEL, ) -> np.ndarray: """ Resample a rest-frame spectrum onto an observed wavelength grid via Lanczos. Uses the same Numba kernel as the science ``ccf_line_mask`` sampler (:func:`_poly_interp_sorted_1d` / ``mask_ccf_pixel_interp_order``). At injected radial velocity ``rv_m_s`` and barycentric factor ``zb``, .. math:: F_{\\rm obs}(\\lambda) = F_{\\rm rest}\\!\\left( \\lambda\\,\\frac{1+z_b}{1+v/c} \\right) which is the inverse of the mask Doppler map :math:`\\lambda_{\\rm obs}=\\lambda_{\\rm rest}(1+v/c)/(1+z_b)`. Parameters ---------- wave_obs_um Observed wavelengths (um). wave_rest_um, flux_rest Rest-frame knots (um) and fluxes; ``wave_rest_um`` must be strictly ascending. rv_m_s Injected stellar RV (m/s). zb Barycentric redshift factor (same convention as the mask CCF). order Lanczos parameter *a* (default ``3`` = Lanczos-3), matching ``mask_ccf_pixel_interp_order``. ``1`` selects linear interpolation. Clamped to ``[1, MAX_MASK_CCF_PIXEL_INTERP_ORDER]``. prepare_for_obs_grid When set to the target observed wavelength grid (um), densify ``wave_rest_um`` / ``flux_rest`` first via :func:`prepare_template_for_doppler_paint` so the template has enough knots per BSPEC pixel for cm/s Doppler shifts. Omit for mask-CCF sub-pixel sampling on an already-discretized L2 spectrum. prepare_samples_per_pixel Passed to :func:`prepare_template_for_doppler_paint` when ``prepare_for_obs_grid`` is set (default ``8``). Returns ------- np.ndarray Flux on ``wave_obs_um`` (float64). See Also -------- :func:`prepare_template_for_doppler_paint` Instrument-linked template densification before paint. :func:`~hispecdrp.primitives.utils.cubic_spline.doppler_paint_cubic_spline` Alternate not-a-knot cubic paint (not the science/CCF-matching path). """ w_obs = np.asarray(wave_obs_um, dtype=np.float64).ravel() w_rest = np.asarray(wave_rest_um, dtype=np.float64).ravel() f_rest = np.asarray(flux_rest, dtype=np.float64).ravel() if prepare_for_obs_grid is not None: w_rest, f_rest = prepare_template_for_doppler_paint( w_rest, f_rest, np.asarray(prepare_for_obs_grid, dtype=np.float64).ravel(), samples_per_pixel=float(prepare_samples_per_pixel), ) if w_rest.size != f_rest.size: raise ValueError("wave_rest_um and flux_rest must have the same length") if w_rest.size < 1: raise ValueError("need at least one rest-frame knot") if w_rest.size >= 2 and not np.all(np.diff(w_rest) > 0.0): raise ValueError("wave_rest_um must be strictly ascending") pio = int(order) if pio < 1: pio = 1 elif pio > MAX_MASK_CCF_PIXEL_INTERP_ORDER: pio = MAX_MASK_CCF_PIXEL_INTERP_ORDER beta = (1.0 + float(zb)) / (1.0 + float(rv_m_s) / float(C_M_S)) xq = w_obs * beta n = int(w_rest.size) out = np.empty(xq.size, dtype=np.float64) for i in range(xq.size): out[i] = _poly_interp_sorted_1d(float(xq[i]), w_rest, f_rest, n, pio) return out
# Backward-compatible alias (former Lagrange paint name). doppler_paint_lagrange = doppler_paint_lanczos
[docs] @njit(cache=True) def _poly_interp_sorted_1d_value_and_flux_variance( xq: float, x: np.ndarray, y: np.ndarray, e_sig: np.ndarray, n: int, order: int, ) -> tuple[float, float]: """ Interpolate ``y`` at ``xq`` plus propagated variance from pixel σ. Same stencil / weights as :func:`_poly_interp_sorted_1d` (linear or Lanczos-*a*). Returns ``(ŷ, \\sum_m w_m^2 e_sig[m]^2)`` with renormalized weights near edges. Edge clamps return the endpoint sample and its ``e_sig^2``. Returns ``(nan, nan)`` if any stencil ``e_sig`` is non-finite or non-positive. """ if n <= 0: return np.nan, np.nan if n == 1: es = float(e_sig[0]) if not np.isfinite(es) or es <= 0.0: return np.nan, np.nan return float(y[0]), es * es o = int(order) if o < 1: o = 1 if o > MAX_MASK_CCF_PIXEL_INTERP_ORDER: o = MAX_MASK_CCF_PIXEL_INTERP_ORDER if xq <= float(x[0]): es = float(e_sig[0]) if not np.isfinite(es) or es <= 0.0: return np.nan, np.nan return float(y[0]), es * es if xq >= float(x[n - 1]): es = float(e_sig[n - 1]) if not np.isfinite(es) or es <= 0.0: return np.nan, np.nan return float(y[n - 1]), es * es if o == 1: j = int(np.searchsorted(x, xq, side="right")) - 1 if j < 0: j = 0 if j >= n - 1: j = n - 2 es0 = float(e_sig[j]) es1 = float(e_sig[j + 1]) if (not np.isfinite(es0) or es0 <= 0.0) or ( not np.isfinite(es1) or es1 <= 0.0 ): return np.nan, np.nan x0 = float(x[j]) x1 = float(x[j + 1]) dx = x1 - x0 if dx == 0.0: return float(y[j]), es0 * es0 t = (xq - x0) / dx w0 = 1.0 - t w1 = t yhat = w0 * float(y[j]) + w1 * float(y[j + 1]) return yhat, w0 * w0 * es0 * es0 + w1 * w1 * es1 * es1 a = float(o) pf = _fractional_pixel_index(xq, x, n) i0 = int(math.floor(pf)) - o + 1 i1 = int(math.floor(pf)) + o if i0 < 0: i0 = 0 if i1 > n - 1: i1 = n - 1 wsum = 0.0 for i in range(i0, i1 + 1): w = _lanczos_kernel(pf - float(i), a) wsum += w if wsum == 0.0: return np.nan, np.nan acc_y = 0.0 acc_var = 0.0 for i in range(i0, i1 + 1): es_m = float(e_sig[i]) if not np.isfinite(es_m) or es_m <= 0.0: return np.nan, np.nan wn = _lanczos_kernel(pf - float(i), a) / wsum acc_y += wn * float(y[i]) acc_var += wn * wn * es_m * es_m return acc_y, acc_var
[docs] @njit(cache=True) def _lagrange_stencil_index_and_weights( xq: float, x: np.ndarray, n: int, order: int, out_L: np.ndarray, ) -> tuple[int, int]: """ Interpolation weights on the same stencil as :func:`_poly_interp_sorted_1d`. Despite the historical name, weights are **linear** (``order==1``) or **renormalized Lanczos-a** (``a=order``). Writes ``out_L[0:k]`` and returns ``(s, k)`` for pixel indices ``s … s+k-1``. Clamped endpoints use a one-point stencil with ``L[0]=1``. Returns ``(-1, 0)`` if invalid. """ if n <= 0: return -1, 0 if n == 1: out_L[0] = 1.0 return 0, 1 o = int(order) if o < 1: o = 1 if o > MAX_MASK_CCF_PIXEL_INTERP_ORDER: o = MAX_MASK_CCF_PIXEL_INTERP_ORDER if xq <= float(x[0]): out_L[0] = 1.0 return 0, 1 if xq >= float(x[n - 1]): out_L[0] = 1.0 return n - 1, 1 if o == 1: j = int(np.searchsorted(x, xq, side="right")) - 1 if j < 0: j = 0 if j >= n - 1: j = n - 2 x0 = float(x[j]) x1 = float(x[j + 1]) dx = x1 - x0 if dx == 0.0: out_L[0] = 1.0 return j, 1 t = (xq - x0) / dx out_L[0] = 1.0 - t out_L[1] = t return j, 2 a = float(o) pf = _fractional_pixel_index(xq, x, n) i0 = int(math.floor(pf)) - o + 1 i1 = int(math.floor(pf)) + o if i0 < 0: i0 = 0 if i1 > n - 1: i1 = n - 1 k = i1 - i0 + 1 if k <= 0 or k > out_L.shape[0]: return -1, 0 wsum = 0.0 for m in range(k): w = _lanczos_kernel(pf - float(i0 + m), a) out_L[m] = w wsum += w if wsum == 0.0: return -1, 0 inv = 1.0 / wsum for m in range(k): out_L[m] *= inv return i0, k
[docs] @njit(cache=True, parallel=True) def _calc_mask_ccf_chunks_numba( left_edges_2d: np.ndarray, right_edges_2d: np.ndarray, s_use_2d: np.ndarray, e_use_2d: np.ndarray, sn_2d: np.ndarray, n_pix_arr: np.ndarray, v_grid_m_s: np.ndarray, zb: float, line_lambda_rest_2d: np.ndarray, line_left_rest_2d: np.ndarray, line_right_rest_2d: np.ndarray, line_w_2d: np.ndarray, n_line_arr: np.ndarray, compute_line_std: bool, pixel_interp_order: int, tophat_segment_samples: int, ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """ Chunk-batched mask CCF(v) with parallelism over chunks. **Delta-line model:** each mask line is a rest wavelength :math:`\\lambda_{\\rm rest}`. At trial velocity :math:`v`, the observed wavelength is :math:`\\lambda_{\\rm obs} = \\lambda_{\\rm rest}\\,(1+v/c)/(1+z_b)`. **Tophat segment model (finite width):** each mask entry has rest edges :math:`[\\lambda_{\\rm lo},\\lambda_{\\rm hi}]`. At trial velocity the observed segment is shifted by the same factor as above. The segment’s contribution is approximated by averaging :math:`F\\cdot\\mathrm{SN}` over ``tophat_segment_samples`` uniformly spaced points inside the shifted segment. For each velocity, let :math:`x_j = F_j\\,\\mathrm{SN}_j` at each contributing line (interpolated on pixel centers). Accumulate :math:`\\sum_j w_j x_j` and :math:`\\sum_j w_j x_j^2` over lines whose shifted :math:`\\lambda_{\\rm obs}` lies in the chunk with finite :math:`F` and :math:`\\mathrm{SN}`. The CCF is the weighted mean :math:`\\mathrm{CCF}(v)=\\sum_j w_j x_j\\,/\\,\\sum_j w_j`. **Flux errors:** ``e_use_2d`` holds per-pixel flux :math:`\\sigma` on the chunk grid. The mask statistic is linear in pixel values :math:`G_m` (Lanczos / linear interpolation of flux per line, :math:`\\mathrm{SN}_j` treated as exact on the stencil): :math:`C = \\sum_m c_m G_m` with :math:`c_m = \\sum_j (w_j/W)\\,\\mathrm{SN}_j\\,L^{(j)}_{m}` where :math:`W=\\sum_j w_j` and :math:`L^{(j)}_{m}` is the interpolator weight of pixel :math:`m` for line :math:`j` (zero outside that line's stencil). Under independent pixel noise, :math:`\\sigma_{\\mathrm{meas}}^2 = \\sum_m c_m^2 \\sigma_m^2`. This **co-adds** lines that share stencil pixels and replaces the earlier :math:`\\sum_j w_j^2\\mathrm{Var}(F_j)/W^2` independent-line sum, which **inflated** :math:`\\sigma_{\\mathrm{meas}}` when many lines reused the same pixels. The **systematic / excess line-to-line** component is the usual weighted dispersion of :math:`x_j` about :math:`C`: .. math:: \\sigma_{\\mathrm{line}}^2 = \\max\\left(0,\\; \\frac{\\sum_j w_j x_j^2}{\\sum_j w_j} - C^2\\right)\\,. When ``compute_line_std`` is True, the second output is the **flux-propagated** measurement uncertainty :math:`\\sigma_{\\mathrm{meas}}` (independent pixel noise through the interpolator stencil). A line-to-line flux scatter :math:`\\sigma_{\\mathrm{line}}` is still accumulated internally but is **not** added in quadrature: that term is a depth-dispersion floor, not jitter on the CCF centroid, and would freeze :math:`\\sigma_\\mu` at the LSF width even at infinite S/N. The third output stores the same :math:`\\sigma_{\\mathrm{meas}}` (``nan`` when unavailable). Input arrays are padded to fixed widths; ``n_pix_arr`` and ``n_line_arr`` give valid lengths for each chunk row. """ n_chunk = left_edges_2d.shape[0] n_v = v_grid_m_s.shape[0] n_line_pad = line_lambda_rest_2d.shape[1] out_ccf = np.full((n_chunk, n_v), np.nan, dtype=np.float64) if compute_line_std: out_std = np.full((n_chunk, n_v), np.nan, dtype=np.float64) out_sigma_flux = np.full((n_chunk, n_v), np.nan, dtype=np.float64) else: out_std = np.empty((0, 0), dtype=np.float64) out_sigma_flux = np.empty((0, 0), dtype=np.float64) zb1 = 1.0 + zb for ic in prange(n_chunk): n_pix = int(n_pix_arr[ic]) n_ln = int(n_line_arr[ic]) if n_pix <= 0 or n_ln <= 0: continue chunk_lo = left_edges_2d[ic, 0] chunk_hi = right_edges_2d[ic, n_pix - 1] centers = np.empty(n_pix, dtype=np.float64) for n in range(n_pix): centers[n] = 0.5 * ( left_edges_2d[ic, n] + right_edges_2d[ic, n] ) lag_L_buf = np.empty(_MAX_PIXEL_INTERP_STENCIL, dtype=np.float64) coef_pix = np.zeros(n_pix, dtype=np.float64) n_samp = int(tophat_segment_samples) if n_samp < 1: n_samp = 1 for i_v in range(n_v): sh = (1.0 + v_grid_m_s[i_v] / C_M_S) / zb1 total = 0.0 w_sum = 0.0 sum_wx2 = 0.0 for j in range(n_ln): lam_rest = line_lambda_rest_2d[ic, j] if not np.isfinite(lam_rest) or lam_rest <= 0.0: continue wj = line_w_2d[ic, j] if not np.isfinite(wj) or wj <= 0.0: continue lam_lo_r = line_left_rest_2d[ic, j] lam_hi_r = line_right_rest_2d[ic, j] finite_edges = ( np.isfinite(lam_lo_r) and np.isfinite(lam_hi_r) and lam_hi_r >= lam_lo_r and lam_lo_r > 0.0 ) if finite_edges and lam_hi_r > lam_lo_r: # Finite-width tophat segment: average samples across the segment. lam_lo = lam_lo_r * sh lam_hi = lam_hi_r * sh if lam_hi < chunk_lo or lam_lo > chunk_hi: continue # Clamp to chunk support to avoid sampling outside pixels. if lam_lo < chunk_lo: lam_lo = chunk_lo if lam_hi > chunk_hi: lam_hi = chunk_hi if lam_hi <= lam_lo: continue acc = 0.0 n_ok = 0 for t0 in range(n_samp): frac = (t0 + 0.5) / float(n_samp) lam0 = lam_lo + frac * (lam_hi - lam_lo) fv = _poly_interp_sorted_1d( lam0, centers, s_use_2d[ic, :], n_pix, pixel_interp_order ) snv = _poly_interp_sorted_1d( lam0, centers, sn_2d[ic, :], n_pix, pixel_interp_order ) if not (np.isfinite(fv) and np.isfinite(snv)): continue acc += fv * snv n_ok += 1 if n_ok <= 0: continue xj = acc / float(n_ok) else: # Zero-width line (delta): sample at the shifted center. lam0 = lam_rest * sh if lam0 < chunk_lo or lam0 > chunk_hi: continue fv = _poly_interp_sorted_1d( lam0, centers, s_use_2d[ic, :], n_pix, pixel_interp_order ) snv = _poly_interp_sorted_1d( lam0, centers, sn_2d[ic, :], n_pix, pixel_interp_order ) if not (np.isfinite(fv) and np.isfinite(snv)): continue xj = fv * snv partial = wj * xj total += partial w_sum += wj sum_wx2 += wj * xj * xj if w_sum > 0.0: inv_w = 1.0 / w_sum ccf = total * inv_w out_ccf[ic, i_v] = ccf if compute_line_std: mean_x2 = sum_wx2 * inv_w var_line = mean_x2 - ccf * ccf if var_line < 0.0: var_line = 0.0 sig_line = math.sqrt(var_line) for mm in range(n_pix): coef_pix[mm] = 0.0 for j in range(n_ln): lam_rest = line_lambda_rest_2d[ic, j] if not np.isfinite(lam_rest) or lam_rest <= 0.0: continue wj = line_w_2d[ic, j] if not np.isfinite(wj) or wj <= 0.0: continue lam_lo_r = line_left_rest_2d[ic, j] lam_hi_r = line_right_rest_2d[ic, j] finite_edges = ( np.isfinite(lam_lo_r) and np.isfinite(lam_hi_r) and lam_hi_r >= lam_lo_r and lam_lo_r > 0.0 ) if finite_edges and lam_hi_r > lam_lo_r: lam_lo = lam_lo_r * sh lam_hi = lam_hi_r * sh if lam_hi < chunk_lo or lam_lo > chunk_hi: continue if lam_lo < chunk_lo: lam_lo = chunk_lo if lam_hi > chunk_hi: lam_hi = chunk_hi if lam_hi <= lam_lo: continue # Average coefficient contributions across segment samples. for t0 in range(n_samp): frac = (t0 + 0.5) / float(n_samp) lam0 = lam_lo + frac * (lam_hi - lam_lo) s_l, k_l = _lagrange_stencil_index_and_weights( lam0, centers, n_pix, pixel_interp_order, lag_L_buf, ) if s_l < 0 or k_l <= 0: continue snv = _poly_interp_sorted_1d( lam0, centers, sn_2d[ic, :], n_pix, pixel_interp_order ) if not np.isfinite(snv): continue pref = (wj * inv_w * snv) / float(n_samp) for t in range(k_l): coef_pix[s_l + t] += pref * lag_L_buf[t] else: lam0 = lam_rest * sh if lam0 < chunk_lo or lam0 > chunk_hi: continue s_l, k_l = _lagrange_stencil_index_and_weights( lam0, centers, n_pix, pixel_interp_order, lag_L_buf, ) if s_l < 0 or k_l <= 0: continue snv = _poly_interp_sorted_1d( lam0, centers, sn_2d[ic, :], n_pix, pixel_interp_order ) if not np.isfinite(snv): continue pref = wj * inv_w * snv for t in range(k_l): coef_pix[s_l + t] += pref * lag_L_buf[t] sig_meas_sq = 0.0 for m in range(n_pix): cm = float(coef_pix[m]) if cm != 0.0: em = float(e_use_2d[ic, m]) if np.isfinite(em) and em > 0.0: sig_meas_sq += cm * cm * em * em sig_meas = math.sqrt(sig_meas_sq) out_sigma_flux[ic, i_v] = sig_meas # Centroid weights use pixel-propagated σ only (not σ_line). out_std[ic, i_v] = sig_meas else: out_ccf[ic, i_v] = np.nan if compute_line_std: out_sigma_flux[ic, i_v] = np.nan out_std[ic, i_v] = np.nan return out_ccf, out_std, out_sigma_flux
[docs] @njit(cache=True) def _ccf_rv_numba_err_floor(vs: float) -> float: """Match :func:`_ccf_rv_err_numeric_floor` (m/s); sub-grid σ_RV allowed.""" ax = abs(vs) if ax < 1.0e-30: ax = 1.0 return max(1.0e-9 * ax, 1.0e-12)
[docs] @njit(cache=True) def _nanmedian_numba_1d(x: np.ndarray) -> float: vals = np.empty(x.size, dtype=np.float64) n = 0 for i in range(x.size): xi = x[i] if np.isfinite(xi): vals[n] = xi n += 1 if n == 0: return np.nan vv = np.sort(vals[:n]) mid = n // 2 if (n % 2) == 1: return float(vv[mid]) return float(0.5 * (vv[mid - 1] + vv[mid]))
[docs] @njit(cache=True) def _smooth_uniform5_numba(y: np.ndarray, n: int) -> np.ndarray: """5-point moving average; non-finite samples excluded from each local mean.""" ys = np.empty(n, dtype=np.float64) for i in range(n): s = 0.0 c = 0.0 for k in range(i - 2, i + 3): if 0 <= k < n: yk = float(y[k]) if np.isfinite(yk): s += yk c += 1.0 if c > 0.0: ys[i] = s / c else: ys[i] = np.nan return ys
[docs] @njit(cache=True) def _line_mask_peak_index_integral_and_prominence( ys: np.ndarray, n: int, prom_half_width: int, integral_half_width: int, ) -> int: """ Choose among strict local maxima of the smoothed CCF using **integrated excess** (sum of positive deviation from the global median in a wide window) times ``sqrt(prominence + 1)``. Pure prominence favors **narrow** spikes (large drop to a nearby valley). The physical stellar-RV peak from thousands of mask lines is **broad**; its prominence can be modest while the integrated contrast in ±~20–40 km/s is large. Combining integral × √prominence prefers that coherent peak over spurious narrow maxima (e.g. grid artifacts near unrelated velocities). """ W = prom_half_width if W < 3: W = 3 Wi = integral_half_width if Wi < 10: Wi = 10 y_med = _nanmedian_numba_1d(ys) if not np.isfinite(y_med): y_med = 0.0 best_i = -1 best_score = -np.inf best_y = -np.inf for i in range(1, n - 1): yi = ys[i] ym = ys[i - 1] yp = ys[i + 1] if not (np.isfinite(yi) and np.isfinite(ym) and np.isfinite(yp)): continue if not (yi > ym and yi > yp): continue lo = i - W if lo < 0: lo = 0 hi = i + W + 1 if hi > n: hi = n left_min = np.inf for j in range(lo, i): yj = ys[j] if np.isfinite(yj) and yj < left_min: left_min = yj right_min = np.inf for j in range(i + 1, hi): yj = ys[j] if np.isfinite(yj) and yj < right_min: right_min = yj if not np.isfinite(left_min) or not np.isfinite(right_min): continue base = left_min if right_min > base: base = right_min prom = yi - base if prom <= 0.0: continue lo2 = i - Wi if lo2 < 0: lo2 = 0 hi2 = i + Wi + 1 if hi2 > n: hi2 = n integral = 0.0 for j in range(lo2, hi2): yj = ys[j] if np.isfinite(yj) and yj > y_med: integral += yj - y_med score = integral * np.sqrt(prom + 1.0) if score > best_score or (score == best_score and yi > best_y): best_score = score best_i = i best_y = yi if best_i >= 0: return best_i # Fallback: global maximum of smoothed profile ig = -1 yg = -np.inf for i in range(n): yi = ys[i] if np.isfinite(yi) and yi > yg: yg = yi ig = i return ig
[docs] @njit(cache=True) def _rv_from_ccf_line_mask_peak_index_numba( v_grid_m_s: np.ndarray, ccf_raw: np.ndarray, i_peak_prior: int, ) -> int: """ Peak index used by :func:`_rv_from_ccf_line_mask_numba_single` for LSTSQ / fallback paths. Returns ``-1`` if the grid is invalid or no usable peak is found before edge handling. """ n = v_grid_m_s.size if ccf_raw.size != n: return -1 baseline_raw = _nanmedian_numba_1d(ccf_raw) if not np.isfinite(baseline_raw): return -1 sign = -1.0 y_work = np.empty(n, dtype=np.float64) for i in range(n): yi = ccf_raw[i] if np.isfinite(yi): y_work[i] = sign * yi else: y_work[i] = np.nan if i_peak_prior >= 0 and i_peak_prior < n: i_peak = i_peak_prior else: ys = _smooth_uniform5_numba(y_work, n) Wprom = n // 10 if Wprom < 80: Wprom = 80 if Wprom > 2000: Wprom = 2000 Wint = n // 12 if Wint < 100: Wint = 100 if Wint > 800: Wint = 800 i_peak = _line_mask_peak_index_integral_and_prominence(ys, n, Wprom, Wint) if i_peak < 0 or i_peak >= n: return -1 return int(i_peak)
[docs] @njit(cache=True) def _rv_from_ccf_line_mask_numba_single( v_grid_m_s: np.ndarray, ccf_raw: np.ndarray, n_good: int, i_peak_prior: int, ) -> tuple[float, float, int]: """ Fast Numba seed RV from mask-line CCF (discrete peak + heuristic σ). Convention is **fixed by algorithm**, not inferred from each CCF shape: the mask weights target **absorption** lines, so the weight-normalized statistic is minimized near the correct Doppler shift. We always work in ``-CCF`` (search maxima), and ``flipped`` is always 1 so returned/preview CCF rows are negated consistently. ``ccf_raw`` is the weight-normalized mask CCF row from :func:`_calc_mask_ccf_chunks_numba`. This estimate is only a fallback when the Gaussian CCF fit does not succeed; the pipeline final RV is the Gaussian centroid from :func:`fit_ccf_rv`. """ n = v_grid_m_s.size if ccf_raw.size != n: return np.nan, np.nan, 0 baseline_raw = _nanmedian_numba_1d(ccf_raw) if not np.isfinite(baseline_raw): return np.nan, np.nan, 0 sign = -1.0 flipped = 1 y_work = np.empty(n, dtype=np.float64) for i in range(n): yi = ccf_raw[i] if np.isfinite(yi): y_work[i] = sign * yi else: y_work[i] = np.nan if i_peak_prior >= 0 and i_peak_prior < n: i_peak = i_peak_prior else: ys = _smooth_uniform5_numba(y_work, n) Wprom = n // 10 if Wprom < 80: Wprom = 80 if Wprom > 2000: Wprom = 2000 Wint = n // 12 if Wint < 100: Wint = 100 if Wint > 800: Wint = 800 i_peak = _line_mask_peak_index_integral_and_prominence(ys, n, Wprom, Wint) if i_peak < 0 or i_peak >= n: return np.nan, np.nan, flipped v_peak = float(v_grid_m_s[i_peak]) v_step_edge = float(abs(v_grid_m_s[1] - v_grid_m_s[0])) if n > 1 else 1.0 if i_peak <= 0 or i_peak >= (n - 1): fl = _ccf_rv_numba_err_floor(v_step_edge) rv_err_edge = max(float(v_step_edge * 2.0), fl) return v_peak, rv_err_edge, flipped v0 = float(v_grid_m_s[i_peak - 1]) v1 = float(v_grid_m_s[i_peak]) v2 = float(v_grid_m_s[i_peak + 1]) h_m = v1 - v0 h_p = v2 - v1 v_step_eff = 0.5 * (h_m + h_p) if h_m <= 0.0 or h_p <= 0.0: fl = _ccf_rv_numba_err_floor(v_step_eff) return v_peak, max(float(abs(v_step_eff) * 2.0), fl), flipped y_0 = float(sign * ccf_raw[i_peak]) baseline = float(sign * baseline_raw) amp = y_0 - baseline fl = _ccf_rv_numba_err_floor(v_step_eff) if not np.isfinite(amp) or amp <= 0.0: return v_peak, max(float(abs(v_step_eff) * 2.0), fl), flipped # Discrete-grid peak seed; formal σ is a coarse heuristic (Gaussian fit replaces both). n_scale = max(float(n_good), 1.0) rv_err = float(max(float(abs(v_step_eff) * 2.0) / np.sqrt(n_scale), fl)) return float(v_peak), float(rv_err), flipped
[docs] @njit(parallel=True, cache=True) def _rv_from_ccf_line_mask_rows_numba( v_grid_m_s: np.ndarray, ccf_rows: np.ndarray, n_good_arr: np.ndarray, out_rv: np.ndarray, out_rv_err: np.ndarray, out_flip: np.ndarray, i_peak_prior: int, ) -> None: n_chunk = ccf_rows.shape[0] for i in prange(n_chunk): rv, rv_err, flipped = _rv_from_ccf_line_mask_numba_single( v_grid_m_s, ccf_rows[i], int(n_good_arr[i]), int(i_peak_prior), ) out_rv[i] = rv out_rv_err[i] = rv_err out_flip[i] = flipped
[docs] def rv_per_chunks_line_mask( wave_um: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, dq_bad_mask: np.ndarray, mask_lines: MaskLines, *, window_size_um: float, v_min_m_s: float = V_MIN_DEFAULT_M_S, v_max_m_s: float = V_MAX_DEFAULT_M_S, v_step_m_s: float = V_STEP_DEFAULT_M_S, v_grid_m_s: np.ndarray | None = None, zb: float = 0.0, max_cores: int | None = None, return_ccf: bool = False, min_good_pixels: int = 10, mask_ccf_pixel_interp_order: int = 3, window_line_by_line: bool = False, line_mask_line_chunk_v_center_m_s: float | None = None, gaussian_seed_mean_m_s: float | None = None, ) -> tuple[ np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray | None, np.ndarray, np.ndarray, np.ndarray, np.ndarray | None, np.ndarray | None, ]: """ Compute per-chunk RVs and optional CCF stacks for one echelle order. By default splits the order into equal-wavelength bins (count from :func:`ccf_order_n_chunks_for_span` given the order span and ``window_size_um``), then computes chunk CCF rows in one Numba batch via :func:`_calc_mask_ccf_chunks_numba` (parallel over chunks; delta-line interpolation at each Doppler-shifted rest wavelength), followed by a Numba chunk-parallel discrete-peak seed. Chunks on an echelle row are iterated **longest λ first** (descending chunk-center wavelength, red → blue along the row), so downstream ``RVCCF`` rows and mask-overlay segments follow the same ordering as ascending echelle order in the exposure. RV extraction assumes a **fixed absorption-line convention** for all chunks and orders (fit on ``-CCF``, not data-driven emission/absorption guessing). Peak selection uses a 5-point smoothed CCF and a **combined score** (wide-window integrated excess above the global median times ``√prominence``) over strict local maxima—favoring the broad, physically coherent peak at the true RV over narrow spurious maxima. A fast Numba estimate is computed first; then chunk RVs are updated with a **Numba-parallel** Gaussian+fixed-baseline LM centroid (:func:`~hispecdrp.primitives.utils.ccf.ccf_gauss_fit_numba.fit_ccf_rv_rows_numba`, same peak-up / fixed-baseline convention as :func:`fit_ccf_rv` for line-mask rows). If the Gaussian path does not return a finite RV, the Numba seed is kept. Returns flattened lists of chunk centers and RVs. ``ccf_2d`` is the weight-normalized mask CCF used for RV extraction and stacking; ``ccf_preview_2d`` holds the same rows before the per-chunk sign flip applied for ``ccf_2d`` (both match the physical weighted CCF up to that convention). Parameters ---------- wave_um, spec, spec_err : np.ndarray Wavelength (µm), flux, and error; same length. Detector order may decrease in λ (HDF WAVE); each chunk is sorted to increasing λ before pixel edges and interpolation. dq_bad_mask : np.ndarray True where pixel should be excluded (e.g. DO_NOT_USE). mask_lines : MaskLines Full-order mask; restricted per chunk via :func:`~hispecdrp.utils.line_mask_utils.restrict_mask_to_chunk`. window_size_um : float Target maximum segment width in µm; one full-order chunk if span ≤ this value. Ignored for chunk **count** when ``window_line_by_line`` is true (still used for the symmetric spectral band about each line’s predicted λ). v_min_m_s, v_max_m_s, v_step_m_s : float, optional Velocity search grid (m s⁻¹). Ignored when ``v_grid_m_s`` is provided. v_grid_m_s : np.ndarray or None, optional Explicit velocity samples (m s⁻¹), e.g. from :func:`build_centered_uniform_velocity_grid`. When set, ``v_min_m_s`` / ``v_max_m_s`` / ``v_step_m_s`` are not used to build the grid, but together with ``v_grid_m_s`` they still define the velocity span used to restrict mask lines per chunk via :func:`~hispecdrp.utils.line_mask_utils.restrict_mask_to_chunk` (same coarse bounds passed in). zb : float, optional Barycentric factor passed to the CCF shift. max_cores : int or None, optional Numba thread count cap for chunk-parallel CCF evaluation and the Numba-parallel Gaussian centroid batch (:func:`~hispecdrp.utils.parallelization_utils.numba_thread_scope` around :func:`_calc_mask_ccf_chunks_numba` / :func:`~hispecdrp.primitives.utils.ccf.ccf_gauss_fit_numba.fit_ccf_rv_rows_numba`). return_ccf : bool, optional If True, also return mean CCF rows per chunk (stacked for preview). min_good_pixels : int, optional Minimum unmasked finite pixels required per chunk. mask_ccf_pixel_interp_order : int, optional Lanczos parameter *a* for sampling flux onto Doppler-shifted mask wavelengths (``1`` = linear; default ``3`` = Lanczos-3). Clamped to ``[1, MAX_MASK_CCF_PIXEL_INTERP_ORDER]``. window_line_by_line : bool, optional When true, chunk by mask lines (requires finite ``line_mask_line_chunk_v_center_m_s``). line_mask_line_chunk_v_center_m_s : float or None, optional Observed-frame line-window center (m s⁻¹) for line-by-line chunking; also preferred Gaussian-fit seed when set. gaussian_seed_mean_m_s : float or None, optional Optional Gaussian-fit seed (m s⁻¹) when ``line_mask_line_chunk_v_center_m_s`` is unset (e.g. centered-grid / auto-scout center). Returns ------- rvs : np.ndarray Per-chunk RV (m s⁻¹). After the Numba seed, each chunk is replaced by the Numba-parallel Gaussian centroid when that fit returns a finite value; otherwise the Numba seed is kept. rv_errs : np.ndarray Per-chunk RV uncertainty (m s\\ :sup:`−1`): Gaussian fit uncertainty when that path succeeds; otherwise the Numba heuristic from :func:`_rv_from_ccf_line_mask_numba_single`. centers : np.ndarray Chunk center wavelength (µm). v_grid : np.ndarray Velocity grid used for the CCF. ccf_2d : np.ndarray or None If ``return_ccf``, shape ``(n_chunks, n_v)`` of weight-normalized CCF rows, **sign-flipped** per chunk to match the stored absorption-peak convention; used for RVCCF supplements and chunk-level diagnostics. Else ``None``. wl_lo, wl_hi : np.ndarray Per-chunk wavelength bounds (µm), same length as ``rvs``. n_good : np.ndarray Per-chunk count of good pixels used in the mask CCF. ccf_line_std_2d : np.ndarray or None If ``return_ccf``, shape ``(n_chunks, n_v)``: per-velocity **flux-error–propagated** interpolator uncertainty :math:`\\sigma_{\\mathrm{meas}}` (see :func:`_calc_mask_ccf_chunks_numba`). Line-to-line flux scatter is not included. Not flipped with the CCF row; use as a symmetric band around ``ccf_preview_2d``. If ``return_ccf`` is False, ``None``. ccf_preview_2d : np.ndarray or None If ``return_ccf``, same shape as ``ccf_2d``: **weight-normalized** mask CCF (matching :func:`_calc_mask_ccf_chunks_numba`) **before** the per-chunk sign flip applied for ``ccf_2d``. Else ``None``. """ w = np.asarray(wave_um, dtype=np.float64).ravel() s = np.asarray(spec, dtype=np.float64).ravel() e = np.asarray(spec_err, dtype=np.float64).ravel() d = np.asarray(dq_bad_mask, dtype=bool).ravel() def _empty(v_grid_local: np.ndarray): z = np.array([], dtype=np.float64) zi = np.array([], dtype=np.int32) if not return_ccf: return (z, z, z, v_grid_local, None, z, z, zi, None, None, z, z) ccf_out = np.empty((0, len(v_grid_local)), dtype=np.float64) std_out = np.empty((0, len(v_grid_local)), dtype=np.float64) return (z, z, z, v_grid_local, ccf_out, z, z, zi, std_out, ccf_out, z, z) vr_lo = float(v_min_m_s) vr_hi = float(v_max_m_s) pio = int(mask_ccf_pixel_interp_order) if pio < 1: pio = 1 elif pio > MAX_MASK_CCF_PIXEL_INTERP_ORDER: pio = MAX_MASK_CCF_PIXEL_INTERP_ORDER good_pix = ~d & np.isfinite(w) & np.isfinite(s) & np.isfinite(e) if v_grid_m_s is not None: v_grid = np.asarray(v_grid_m_s, dtype=np.float64).ravel() else: v_grid = np.arange( v_min_m_s, v_max_m_s + 0.5 * v_step_m_s, v_step_m_s, dtype=np.float64, ) if np.sum(good_pix) < min_good_pixels: return _empty(v_grid) w_min, w_max = float(np.nanmin(w)), float(np.nanmax(w)) if not np.isfinite(w_min) or not np.isfinite(w_max) or w_max <= w_min: return _empty(v_grid) span_um = float(w_max - w_min) use_line_chunks = bool(window_line_by_line) # Wavelength tolerance for treating a chunk's upper bound as the echelle-row edge (inclusive). _w_edge_eps = max(1e-15, abs(float(w_max)) * 1e-12) if use_line_chunks: if line_mask_line_chunk_v_center_m_s is None or not math.isfinite( float(line_mask_line_chunk_v_center_m_s) ): raise ValueError( "rv_per_chunks_line_mask: window_line_by_line requires finite " "line_mask_line_chunk_v_center_m_s (e.g. ccf_input_velocity in m/s)." ) wl_lo_b, wl_hi_b, wl_ctr_b = build_line_mask_chunk_wavelength_intervals_line_by_line( w, mask_lines, v_center_m_s=float(line_mask_line_chunk_v_center_m_s), zb=float(zb), min_good_pixels=int(min_good_pixels), ) n_chunk = int(len(wl_lo_b)) chunk_iter_fwd: list[tuple[float, float, float, bool]] = [ ( float(wl_lo_b[k]), float(wl_hi_b[k]), float(wl_ctr_b[k]), float(wl_hi_b[k]) >= float(w_max) - _w_edge_eps, ) for k in range(n_chunk) ] chunk_iter = list(reversed(chunk_iter_fwd)) else: n_chunk = ccf_order_n_chunks_for_span(span_um, float(window_size_um)) chunk_iter_fwd = [ ( w_min + k * span_um / n_chunk, w_min + (k + 1) * span_um / n_chunk, 0.5 * ( w_min + k * span_um / n_chunk + w_min + (k + 1) * span_um / n_chunk ), (w_min + (k + 1) * span_um / n_chunk) >= float(w_max) - _w_edge_eps, ) for k in range(n_chunk) ] chunk_iter = list(reversed(chunk_iter_fwd)) all_rvs: list[float] = [] all_rv_errs: list[float] = [] all_centers: list[float] = [] all_wl_lo: list[float] = [] all_wl_hi: list[float] = [] all_n_good_out: list[int] = [] all_ccf_rows: list[np.ndarray] = [] all_ccf_preview_rows: list[np.ndarray] = [] all_ccf_std_rows: list[np.ndarray] = [] chunk_payloads: list[ tuple[ np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, float, float, float, int, ] ] = [] for lam_lo, lam_hi, wl_center, right_closed in chunk_iter: if right_closed: in_voronoi = (w >= lam_lo) & (w <= lam_hi) & np.isfinite(s) & np.isfinite(e) & (~d) else: in_voronoi = (w >= lam_lo) & (w < lam_hi) & np.isfinite(s) & np.isfinite(e) & (~d) band_lo = float(lam_lo) band_hi = float(lam_hi) v_span_lo_um = float(lam_lo) v_span_hi_um = float(lam_hi) if use_line_chunks: band_lo, band_hi = mask_line_window_spectrum_band_um( float(wl_center), float(window_size_um), w_min, w_max, ) in_band = (w >= band_lo) & (w <= band_hi) & np.isfinite(s) & np.isfinite(e) & (~d) in_chunk = in_voronoi & in_band if int(np.sum(in_chunk)) < int(min_good_pixels): in_chunk = in_voronoi v_span_lo_um, v_span_hi_um = float(lam_lo), float(lam_hi) else: v_span_lo_um, v_span_hi_um = float(band_lo), float(band_hi) else: in_chunk = in_voronoi if int(np.sum(in_chunk)) < min_good_pixels: continue w_c = w[in_chunk] s_c = s[in_chunk] e_c = e[in_chunk] # Pixel-edge CCF and ``_poly_interp_sorted_1d`` require increasing λ. # Native HDF WAVE often decreases along detector rows. order_w = np.argsort(w_c, kind="mergesort") w_c = w_c[order_w] s_c = s_c[order_w] e_c = e_c[order_w] # Restrict mask lines so we don't waste time on lines that cannot land in this # chunk for any trial velocity in the search range. if use_line_chunks: v_r_lo, v_r_hi = line_mask_chunk_restrict_velocity_range_m_s( v_span_lo_um, v_span_hi_um, v_prior_m_s=float(line_mask_line_chunk_v_center_m_s), v_span_lo=vr_lo, v_span_hi=vr_hi, ) else: v_r_lo, v_r_hi = vr_lo, vr_hi mask_c = restrict_mask_to_chunk( mask_lines, float(np.nanmin(w_c)), float(np.nanmax(w_c)), v_min_m_s=v_r_lo, v_max_m_s=v_r_hi, zb=zb, ) if mask_c.line_lambda_um.size == 0: continue left_edges, right_edges = pixel_edges_from_wavelength(w_c) pixel_width = right_edges - left_edges pixel_width = np.where(pixel_width > 0, pixel_width, np.nan) finite = np.isfinite(s_c) & np.isfinite(e_c) & (e_c > 0) & np.isfinite(pixel_width) if int(np.sum(finite)) < min_good_pixels: continue s_use = np.where(finite, s_c, 0.0).astype(np.float64) sn = np.where(finite, 1.0, 0.0).astype(np.float64) e_use = np.where(finite, e_c, 0.0).astype(np.float64) w_lo_out = float(np.nanmin(w_c)) w_hi_out = float(np.nanmax(w_c)) chunk_payloads.append( ( left_edges.astype(np.float64), right_edges.astype(np.float64), s_use, sn, e_use, mask_c.line_lambda_um.astype(np.float64), mask_c.line_left_edge.to_value(u.um).astype(np.float64), mask_c.line_right_edge.to_value(u.um).astype(np.float64), mask_c.weight.astype(np.float64), w_lo_out, w_hi_out, float(wl_center), int(np.sum(in_chunk)), ) ) if not chunk_payloads: return _empty(v_grid) n_chunk_valid = len(chunk_payloads) n_pix_max = max(len(t[0]) for t in chunk_payloads) n_line_max = max(len(t[5]) for t in chunk_payloads) left_2d = np.full((n_chunk_valid, n_pix_max), np.nan, dtype=np.float64) right_2d = np.full((n_chunk_valid, n_pix_max), np.nan, dtype=np.float64) s_use_2d = np.zeros((n_chunk_valid, n_pix_max), dtype=np.float64) sn_2d = np.zeros((n_chunk_valid, n_pix_max), dtype=np.float64) e_use_2d = np.zeros((n_chunk_valid, n_pix_max), dtype=np.float64) n_pix_arr = np.zeros(n_chunk_valid, dtype=np.int64) line_lambda_rest_2d = np.full((n_chunk_valid, n_line_max), np.nan, dtype=np.float64) line_left_rest_2d = np.full((n_chunk_valid, n_line_max), np.nan, dtype=np.float64) line_right_rest_2d = np.full((n_chunk_valid, n_line_max), np.nan, dtype=np.float64) line_w_2d = np.zeros((n_chunk_valid, n_line_max), dtype=np.float64) n_line_arr = np.zeros(n_chunk_valid, dtype=np.int64) centers = np.zeros(n_chunk_valid, dtype=np.float64) n_good_arr = np.zeros(n_chunk_valid, dtype=np.int64) wl_lo_arr = np.zeros(n_chunk_valid, dtype=np.float64) wl_hi_arr = np.zeros(n_chunk_valid, dtype=np.float64) for i, payload in enumerate(chunk_payloads): left_i, right_i, s_i, sn_i, e_i, ll_i, lo_i, hi_i, lw_i, lam_lo_i, lam_hi_i, wl_i, ng_i = payload npix = len(left_i) nln = len(ll_i) left_2d[i, :npix] = left_i right_2d[i, :npix] = right_i s_use_2d[i, :npix] = s_i sn_2d[i, :npix] = sn_i e_use_2d[i, :npix] = e_i n_pix_arr[i] = npix line_lambda_rest_2d[i, :nln] = ll_i line_left_rest_2d[i, :nln] = lo_i line_right_rest_2d[i, :nln] = hi_i line_w_2d[i, :nln] = lw_i n_line_arr[i] = nln centers[i] = wl_i n_good_arr[i] = ng_i wl_lo_arr[i] = lam_lo_i wl_hi_arr[i] = lam_hi_i with numba_thread_scope(max_cores): ccf_rows, ccf_std_rows, _ = _calc_mask_ccf_chunks_numba( left_2d, right_2d, s_use_2d, e_use_2d, sn_2d, n_pix_arr, v_grid, float(zb), line_lambda_rest_2d, line_left_rest_2d, line_right_rest_2d, line_w_2d, n_line_arr, True, int(pio), int(TOPHAT_MASK_CCF_SEGMENT_SAMPLES), ) # σ_CCF for the centroid: flux-propagated interpolator SE (σ_meas), not # line-to-line depth scatter. if ccf_std_rows.size > 0: sf = np.asarray(ccf_std_rows, dtype=np.float64) ccf_std_rows = np.where(np.isfinite(sf), np.maximum(0.0, sf), np.nan) ccf_preview_unflipped: np.ndarray | None = ( np.copy(ccf_rows) if bool(return_ccf) else None ) rv_rows = np.empty(n_chunk_valid, dtype=np.float64) rv_err_rows = np.empty(n_chunk_valid, dtype=np.float64) flip_rows = np.zeros(n_chunk_valid, dtype=np.int64) _rv_from_ccf_line_mask_rows_numba( v_grid, ccf_rows, n_good_arr.astype(np.int64), rv_rows, rv_err_rows, flip_rows, -1, ) vg_cc = np.ascontiguousarray(np.asarray(v_grid, dtype=np.float64).ravel(), dtype=np.float64) # Prefer Numba-parallel Gaussian fit (same peak-up / fixed-baseline convention as # :func:`fit_ccf_rv` for line-mask stored rows). Keep Numba RV/σ when the fitter path # does not succeed. Bisector refine is diagnostic only (Queloz BIS / BIS_ERR per chunk). if ( line_mask_line_chunk_v_center_m_s is not None and math.isfinite(float(line_mask_line_chunk_v_center_m_s)) ): v_seed = float(line_mask_line_chunk_v_center_m_s) elif ( gaussian_seed_mean_m_s is not None and math.isfinite(float(gaussian_seed_mean_m_s)) ): v_seed = float(gaussian_seed_mean_m_s) else: v_seed = None # Peak-up rows for the Gaussian LM (match LINE_MASK_CCF_STORED_NEGATED convention). y_fit = np.empty_like(ccf_rows) for i in range(n_chunk_valid): if int(flip_rows[i]) == 1: y_fit[i] = -ccf_rows[i] else: y_fit[i] = ccf_rows[i] err_fit = None if ccf_std_rows.size > 0 and int(ccf_std_rows.shape[1]) == int(vg_cc.size): err_fit = np.ascontiguousarray(ccf_std_rows, dtype=np.float64) cfg_fit = CCF_PREVIEW_SLOT_FIT_CONFIG pix_dv = median_pixel_dv_m_s(wave_um) rv_g_arr, err_g_arr, ok_g_arr = fit_ccf_rv_rows_numba( vg_cc, y_fit, ccf_err_rows=err_fit, gaussian_seed_mean_m_s=v_seed, pass1_half_width_m_s=float(cfg_fit.pass1_half_width_km_s) * 1000.0, pass2_half_width_m_s=float(cfg_fit.pass2_half_width_km_s) * 1000.0, initial_stddev_m_s=float(cfg_fit.initial_stddev_km_s) * 1000.0, levmar_maxiter=int(cfg_fit.levmar_maxiter), min_points=int(cfg_fit.min_points), max_cores=max_cores, pix_size_m_s=pix_dv if math.isfinite(pix_dv) and pix_dv > 0.0 else None, ) v_step_floor = float(effective_ccf_v_step_for_fit(vg_cc)) for i in range(n_chunk_valid): if ( int(ok_g_arr[i]) == 1 and np.isfinite(rv_g_arr[i]) and np.isfinite(err_g_arr[i]) and float(err_g_arr[i]) > 0.0 ): rv_rows[i] = float(rv_g_arr[i]) rv_err_rows[i] = float(err_g_arr[i]) continue # Rare fallback: Astropy LM when the Numba centroid fails (keeps seed otherwise). if not np.isfinite(float(rv_rows[i])): continue e_row = err_fit[i] if err_fit is not None else None try: rv_g, err_g, _par_g, diag_g = fit_ccf_rv( vg_cc, y_fit[i], v_step_floor, n_good=int(n_good_arr[i]), return_params=True, ccf_err=e_row, config=cfg_fit, ccf_line_mask_stored_negated=LINE_MASK_CCF_STORED_NEGATED_FROM_RAW, line_mask_line_window_by_line=bool(window_line_by_line), gaussian_seed_mean_m_s=v_seed, ) except Exception: continue if ( bool(diag_g.get("fit_ok")) and np.isfinite(rv_g) and np.isfinite(err_g) and float(err_g) > 0.0 ): rv_rows[i] = float(rv_g) rv_err_rows[i] = float(err_g) bis_rows = np.full(n_chunk_valid, np.nan, dtype=np.float64) bis_err_rows = np.full(n_chunk_valid, np.nan, dtype=np.float64) def _bisector_one(i: int) -> tuple[int, float, float]: if not np.isfinite(float(rv_rows[i])): return i, float("nan"), float("nan") y_stored = y_fit[i] e_bis = ( err_fit[i] if err_fit is not None else np.ones_like(y_stored) ) try: bis_v, bis_e, *_rest = calc_bisector_inverse_slope(vg_cc, y_stored, e_bis) bv = float(bis_v) if math.isfinite(float(bis_v)) else float("nan") be = float(bis_e) if math.isfinite(float(bis_e)) else float("nan") return i, bv, be except Exception: return i, float("nan"), float("nan") n_bis_workers = resolve_numba_threads(max_cores) if n_chunk_valid > 1 and n_bis_workers > 1: with ThreadPoolExecutor(max_workers=min(n_bis_workers, n_chunk_valid)) as ex: for i, bv, be in ex.map(_bisector_one, range(n_chunk_valid)): bis_rows[i] = bv bis_err_rows[i] = be else: for i in range(n_chunk_valid): _, bv, be = _bisector_one(i) bis_rows[i] = bv bis_err_rows[i] = be all_bis: list[float] = [] all_bis_errs: list[float] = [] for i in range(n_chunk_valid): rv = float(rv_rows[i]) rv_err = float(rv_err_rows[i]) if not np.isfinite(rv): continue all_rvs.append(float(rv)) all_rv_errs.append(float(rv_err) if np.isfinite(rv_err) and rv_err > 0 else np.nan) all_centers.append(float(centers[i])) all_wl_lo.append(float(wl_lo_arr[i])) all_wl_hi.append(float(wl_hi_arr[i])) all_n_good_out.append(int(n_good_arr[i])) all_bis.append(float(bis_rows[i])) all_bis_errs.append(float(bis_err_rows[i])) if return_ccf: all_ccf_rows.append(-ccf_rows[i] if int(flip_rows[i]) == 1 else ccf_rows[i].copy()) pu = ccf_preview_unflipped all_ccf_preview_rows.append( -pu[i] if int(flip_rows[i]) == 1 else pu[i].copy() ) all_ccf_std_rows.append(ccf_std_rows[i].copy()) if not all_rvs: return _empty(v_grid) rvs_arr = np.asarray(all_rvs, dtype=np.float64) rv_errs_arr = np.asarray(all_rv_errs, dtype=np.float64) centers_arr = np.asarray(all_centers, dtype=np.float64) wl_lo_out = np.asarray(all_wl_lo, dtype=np.float64) wl_hi_out = np.asarray(all_wl_hi, dtype=np.float64) n_good_out = np.asarray(all_n_good_out, dtype=np.int32) bis_arr = np.asarray(all_bis, dtype=np.float64) bis_err_arr = np.asarray(all_bis_errs, dtype=np.float64) if return_ccf: ccf_2d = np.vstack(all_ccf_rows).astype(np.float64) if all_ccf_rows else np.empty((0, len(v_grid))) ccf_preview_2d = ( np.vstack(all_ccf_preview_rows).astype(np.float64) if all_ccf_preview_rows else np.empty((0, len(v_grid))) ) ccf_std_2d = ( np.vstack(all_ccf_std_rows).astype(np.float64) if all_ccf_std_rows else np.empty((0, len(v_grid))) ) else: ccf_2d = None ccf_preview_2d = None ccf_std_2d = None return ( rvs_arr, rv_errs_arr, centers_arr, v_grid, ccf_2d, wl_lo_out, wl_hi_out, n_good_out, ccf_std_2d, ccf_preview_2d, bis_arr, bis_err_arr, )
# ============================================================================= # Line-mask per-fiber driver # =============================================================================
[docs] def run_ccf_line_mask_for_fiber( *, input_model, fiber: str, do_orders: list[int], order_vec: list[int], window_size_um: float, mask_path: str | None, mask_wavelength=None, mask_weight=None, v_min_m_s: float = V_MIN_DEFAULT_M_S, v_max_m_s: float = V_MAX_DEFAULT_M_S, v_step_m_s: float = V_STEP_DEFAULT_M_S, ccf_center_m_s: float | None = None, ccf_half_window_m_s: float = 20000.0, zb: float = 0.0, max_cores: int | None = None, want_preview: bool = False, debug_ccf: bool = False, min_good_pixels: int = 10, mask_ccf_pixel_interp_order: int = 3, window_line_by_line: bool = False, ) -> tuple[ np.ndarray, np.ndarray, np.ndarray, np.ndarray, dict | None, Table, ]: """ Run line-mask CCF RV for one fiber (``StellarRVPrimitive(algorithm="ccf_line_mask")``). Reads ``SPEC_FIB*``, ``SPEC_ERR_FIB*``, ``SPEC_DQ_FIB*``, ``WAVE_FIB*`` from ``input_model``, resolves mask lines via :func:`~hispecdrp.utils.line_mask_utils.stellar_rv_ccf_mask_lines`, and processes each requested echelle order with :func:`rv_per_chunks_line_mask`. Per-chunk CCFs use Numba Lanczos / linear sampling (:func:`_calc_mask_ccf_chunks_numba` / :func:`_poly_interp_sorted_1d`, controlled by ``mask_ccf_pixel_interp_order`` and parallelized under ``max_cores``). Final RVs are **Gaussian centroids** from :func:`fit_ccf_rv` (parabolic-vertex refine removed); preview metadata use :func:`finalize_ccf_preview_dict`. Parameters ---------- input_model L2-like datamodel with fiber spectra and wavelengths. fiber : str Fiber label (e.g. ``"A"``) used in attribute names. do_orders : list of int Echelle orders to include. order_vec : list of int Full order indexing aligned with array axis 0. window_size_um : float Wavelength chunk width (µm). mask_path : str or None Path to mask file when not using in-memory ``mask_wavelength`` / ``mask_weight``; ``None`` selects the packaged default (see README). Loaded via :meth:`~hispecdrp.utils.line_mask_utils.MaskLines.load`. mask_wavelength, mask_weight : array-like or None, optional When **both** are set, build the mask in memory (rest wavelengths in µm, weights same length) and ignore ``mask_path`` for loading. See :func:`~hispecdrp.utils.line_mask_utils.stellar_rv_ccf_mask_lines`. v_min_m_s, v_max_m_s, v_step_m_s : float, optional **Broad** uniform velocity search (m s⁻¹). When ``ccf_center_m_s`` is set, only ``v_step_m_s`` is used (as the sampling of the centered window); when unset, they define the sole CCF grid. ccf_center_m_s, ccf_half_window_m_s : float or None When ``ccf_center_m_s`` is finite, CCF is evaluated on a uniform window ``center ± ccf_half_window_m_s`` at ``v_step_m_s`` (:func:`build_centered_uniform_velocity_grid`). When ``None`` / not finite, an **auto-center scout** runs on the broad grid, then all chunks are evaluated on a centered uniform window at the scout peak. zb : float, optional Barycentric factor for mask shift. max_cores : int or None, optional Numba thread count cap forwarded to :func:`rv_per_chunks_line_mask` for chunk-parallel mask CCF evaluation. want_preview : bool, optional If True, build order-averaged CCF data for Plotly preview. debug_ccf : bool, optional Extra logging per order. min_good_pixels : int, optional Minimum unmasked finite spectral pixels required per chunk (see ``rv_per_chunks_line_mask``). mask_ccf_pixel_interp_order : int, optional Lanczos parameter *a* on the echelle wavelength axis when evaluating mask CCFs (``1`` = linear; default ``3`` = Lanczos-3). Forwarded to :func:`rv_per_chunks_line_mask`. window_line_by_line : bool, optional When true, spectral chunks follow mask lines in the observed frame at ``ccf_center_m_s`` (requires finite ``ccf_center_m_s``). Forwarded to :func:`rv_per_chunks_line_mask`. Returns ------- all_wavelengths : np.ndarray Chunk center wavelengths (µm). all_rvs : np.ndarray Per-chunk RVs (m s⁻¹); within one echelle order, values are identical when the order-mean CCF Gaussian fit succeeds. all_rv_errs : np.ndarray Per-chunk uncertainties (same within each order when the Gaussian fit succeeds). all_orders : np.ndarray Echelle order index per chunk (-1 if length mismatch). preview_detail : dict or None Payload for stellar RV preview, or None. rvccf_chunk_supplement : astropy.table.Table Columns ``CHUNK_ID``, ``N_GOOD``, ``V_MIN``, ``V_MAX``, ``V_STEP``, ``N_VEL``, ``CCF`` merged into ``RVCCF_FIB*`` via :func:`assemble_rvccf_fib_table`. Notes ----- Mask and algorithm provenance: module docstring ``References``; ``hispecdrp/data/masks/README.md``. """ logger.info( "CCF line_mask: starting fiber=%s n_do_orders=%d window_um=%.4f want_preview=%s " "debug_ccf=%s (Lanczos mask CCF + Gaussian centroid; max_cores=%s interp_a=%d)", fiber, len(do_orders), window_size_um, want_preview, debug_ccf, max_cores, int(mask_ccf_pixel_interp_order), ) from .ccf_line_mask_spline import line_mask_scout_center_m_s if not np.isfinite(window_size_um) or float(window_size_um) <= 0: raise ValueError("window_size_um must be finite and > 0 for ccf_line_mask") centered = bool( ccf_center_m_s is not None and np.isfinite(float(ccf_center_m_s)) ) if centered: logger.info( "CCF line_mask: centered uniform grid center=%.2f half_width=%.2f step=%.4f (m/s)", float(ccf_center_m_s), float(ccf_half_window_m_s), float(v_step_m_s), ) else: logger.info( "CCF line_mask: velocity grid (m/s) v_min=%.2f v_max=%.2f step=%.4f", float(v_min_m_s), float(v_max_m_s), float(v_step_m_s), ) spec_attr = f"SPEC_FIB{fiber}" err_attr = f"SPEC_ERR_FIB{fiber}" dq_attr = f"SPEC_DQ_FIB{fiber}" wave_attr = f"WAVE_FIB{fiber}" spec = getattr(input_model, spec_attr) err = getattr(input_model, err_attr) if hasattr(input_model, err_attr) else np.ones_like(spec) dq = getattr(input_model, dq_attr) if hasattr(input_model, dq_attr) else np.zeros_like(spec, dtype=np.uint32) wave = getattr(input_model, wave_attr) if err is None: err = np.ones_like(spec, dtype=np.float64) if dq is None: dq = np.zeros_like(spec, dtype=np.uint32) uncal_attr = f"SPEC_UNCAL_FIB{fiber}" uncal_err_attr = f"SPEC_UNCAL_ERR_FIB{fiber}" spec_uncal = getattr(input_model, uncal_attr, None) if hasattr(input_model, uncal_attr) else None spec_uncal_err = ( getattr(input_model, uncal_err_attr, None) if hasattr(input_model, uncal_err_attr) else None ) err = science_centroid_spec_err(spec, err, spec_uncal, spec_uncal_err) # Load mask before building the velocity grid so line-window mode can tighten broad ``v``. mask_lines, mask_src_label = stellar_rv_ccf_mask_lines( mask_path=mask_path, mask_wavelength=mask_wavelength, mask_weight=mask_weight, ) if mask_lines.line_lambda_um.size == 0: raise ValueError(f"Mask loaded no lines: {mask_src_label}") logger.info( "CCF line_mask: loaded mask source=%s n_line_segments=%d", mask_src_label, int(mask_lines.line_lambda_um.size), ) # TODO: refine mask-CCF DQ filtering policy. Today we only gate on DO_NOT_USE; # review which spectral-quality bits are populated in L2 for this path and whether # additional flags (e.g. LOW_INST_TRANS, TELLURIC, OH_LINE) should be excluded. do_not_use = int(DQ_FLAGS.get("DO_NOT_USE", 1)) # We treat any non-zero "do_not_use" bits as bad pixels. bad = (np.asarray(dq, dtype=np.uint32) & do_not_use) != 0 order_tasks = [(oi, order) for oi, order in enumerate(order_vec) if order in do_orders] logger.info( "CCF line_mask: fiber=%s will process n_order_tasks=%d (echelle orders in do_orders)", fiber, len(order_tasks), ) single_order_line_mask = len(order_tasks) == 1 fiber_centered_v_grid: np.ndarray | None = None if window_line_by_line: if not centered or ccf_center_m_s is None: raise ValueError( "run_ccf_line_mask_for_fiber: window_line_by_line requires finite " "ccf_center_m_s (set ccf_input_velocity on the primitive)." ) kw_rv_line_chunking: dict[str, float | bool] = { "window_line_by_line": True, "line_mask_line_chunk_v_center_m_s": float(ccf_center_m_s), } logger.info( "CCF line_mask: line-by-line chunking v_center_m_s=%.2f", float(ccf_center_m_s), ) else: kw_rv_line_chunking = {} v_min_use = float(v_min_m_s) v_max_use = float(v_max_m_s) half_window_use = float(ccf_half_window_m_s) if window_line_by_line and centered: half_window_use, dv_chunk_max = line_mask_line_window_velocity_half_width_m_s( wave, order_tasks, mask_lines, v_center_m_s=float(ccf_center_m_s), zb=float(zb), min_good_pixels=int(min_good_pixels), half_width_m_s=float(ccf_half_window_m_s), v_step_m_s=float(v_step_m_s), ) logger.info( "CCF line_mask: line-window centered half_width=%.2f m/s " "(request=%.2f; max c·Δλ/λ over chunks ≈ %.2f m/s)", half_window_use, float(ccf_half_window_m_s), float(dv_chunk_max), ) if centered: _h_vc = float(ccf_center_m_s) _h_hw = float(half_window_use) v_grid = build_centered_uniform_velocity_grid( _h_vc, _h_hw, float(v_step_m_s), ) v_min_use = float(v_grid[0]) v_max_use = float(v_grid[-1]) else: _h_vc = _h_hw = float("nan") v_grid = np.arange( v_min_use, v_max_use + 0.5 * v_step_m_s, v_step_m_s, dtype=np.float64, ) all_rvs: list[float] = [] all_rv_errs: list[float] = [] all_wavelengths: list[float] = [] all_orders: list[int] = [] # Per-chunk RVs and RVCCF table CCF rows use ``ccf_2d`` from Lanczos mask CCF. want_preview_effective = bool(want_preview) order_slots: list[dict] = [] all_ccf_rows: list[np.ndarray] = [] all_ccf_err_rows: list[np.ndarray] = [] rvccf_rows_accum: list[np.ndarray] = [] rvccf_n_good_accum: list[int] = [] rvccf_bis_accum: list[float] = [] rvccf_bis_err_accum: list[float] = [] # Fiber-level auto-center scout (multi-order): estimate CCF peak on the first valid # echelle row, then reuse the centered uniform velocity grid for every order on this fiber. fiber_scout_center_m_s: float | None = None if not centered and fiber_centered_v_grid is None: for _oi_sc, _ord_sc in order_tasks: _w_sc = np.asarray(wave[_oi_sc], dtype=np.float64) _s_sc = np.asarray(spec[_oi_sc], dtype=np.float64) _e_sc = np.asarray( err[_oi_sc] if getattr(err, "ndim", 0) >= 2 else err, dtype=np.float64 ) _d_sc = np.asarray( bad[_oi_sc] if getattr(bad, "ndim", 0) >= 2 else bad, dtype=bool ) _wmin, _wmax = float(np.nanmin(_w_sc)), float(np.nanmax(_w_sc)) if not np.isfinite(_wmin) or not np.isfinite(_wmax) or _wmax <= _wmin: continue _span = float(_wmax - _wmin) _win_sc = max(float(window_size_um), _span * (1.0 + 1e-12)) _kw_sc = { "min_good_pixels": int(min_good_pixels), "mask_ccf_pixel_interp_order": int(mask_ccf_pixel_interp_order), **kw_rv_line_chunking, } try: _scout = rv_per_chunks_line_mask( _w_sc, _s_sc, _e_sc, _d_sc, mask_lines, window_size_um=_win_sc, v_min_m_s=v_min_use, v_max_m_s=v_max_use, v_step_m_s=v_step_m_s, zb=zb, max_cores=max_cores, return_ccf=True, **_kw_sc, ) except Exception: continue ( _rvs_sc, _errs_sc, _centers_sc, v_grid_sc, ccf_2d_sc, _wl_lo_sc, _wl_hi_sc, _ng_sc, _std_sc, _ccf_preview_sc, _bis_sc, _bis_err_sc, ) = _scout if int(_rvs_sc.size) <= 0: continue vg_sc = np.asarray(v_grid_sc, dtype=np.float64) m_dt = _nanmean_axis0_ignore_empty_columns( np.asarray(ccf_2d_sc, dtype=np.float64) ) # Prefer scout chunk RVs (metrics peak), not argmax on stored CCF. v_c = line_mask_scout_center_m_s(_rvs_sc, vg_sc, m_dt) if math.isfinite(v_c): fiber_scout_center_m_s = float(v_c) fiber_centered_v_grid = build_centered_uniform_velocity_grid( float(v_c), float(ccf_half_window_m_s), float(v_step_m_s), ) logger.info( "CCF line_mask: auto-center scout (fiber-level, order=%s) center=%.2f m/s " "n_vel=%d fiber=%s", _ord_sc, float(v_c), int(fiber_centered_v_grid.size), fiber, ) break # One inverse-variance weight per statistically independent RV estimate (see loop body). fiber_agg_rvs: list[float] = [] fiber_agg_errs: list[float] = [] chunk_fiber_agg_index: list[int] = [] for oi, order in order_tasks: w = np.asarray(wave[oi], dtype=np.float64) s = np.asarray(spec[oi], dtype=np.float64) e = np.asarray(err[oi] if getattr(err, "ndim", 0) >= 2 else err, dtype=np.float64) d_bad = np.asarray(bad[oi] if getattr(bad, "ndim", 0) >= 2 else bad, dtype=bool) w_min, w_max = float(np.nanmin(w)), float(np.nanmax(w)) if not np.isfinite(w_min) or not np.isfinite(w_max) or w_max <= w_min: continue order_ccf_rows: list[np.ndarray] = [] order_v_grid: np.ndarray | None = None order_chunk_rvs: list[float] = [] order_chunk_errs: list[float] = [] order_chunk_wl: list[float] = [] order_chunk_ng: list[int] = [] v_auto_grid: np.ndarray | None = ( np.asarray(fiber_centered_v_grid, dtype=np.float64) if fiber_centered_v_grid is not None and not centered else None ) order_auto_centered = fiber_centered_v_grid is not None and not centered kw_rv = { "min_good_pixels": int(min_good_pixels), "mask_ccf_pixel_interp_order": int(mask_ccf_pixel_interp_order), **kw_rv_line_chunking, } if centered and ccf_center_m_s is not None and math.isfinite(float(ccf_center_m_s)): kw_rv["gaussian_seed_mean_m_s"] = float(ccf_center_m_s) elif ( order_auto_centered and fiber_scout_center_m_s is not None and math.isfinite(float(fiber_scout_center_m_s)) ): # Seed the Gaussian at the scout center on the centered uniform grid. kw_rv["gaussian_seed_mean_m_s"] = float(fiber_scout_center_m_s) # Legacy single-order auto-center scout (when fiber-level scout did not run). span_um = float(w_max - w_min) window_um_scout = max(float(window_size_um), span_um * (1.0 + 1e-12)) if single_order_line_mask and not centered and v_auto_grid is None: scout = rv_per_chunks_line_mask( w, s, e, d_bad, mask_lines, window_size_um=window_um_scout, v_min_m_s=v_min_use, v_max_m_s=v_max_use, v_step_m_s=v_step_m_s, zb=zb, max_cores=max_cores, return_ccf=True, **kw_rv, ) ( _rvs_sc, _errs_sc, _centers_sc, v_grid_sc, ccf_2d_sc, _wl_lo_sc, _wl_hi_sc, _ng_sc, _std_sc, _ccf_preview_sc, _bis_sc, _bis_err_sc, ) = scout if int(_rvs_sc.size) > 0: vg_sc = np.asarray(v_grid_sc, dtype=np.float64) m_dt = _nanmean_axis0_ignore_empty_columns( np.asarray(ccf_2d_sc, dtype=np.float64) ) v_c = line_mask_scout_center_m_s(_rvs_sc, vg_sc, m_dt) if math.isfinite(v_c): fiber_scout_center_m_s = float(v_c) v_auto_grid = build_centered_uniform_velocity_grid( float(v_c), float(ccf_half_window_m_s), float(v_step_m_s), ) order_auto_centered = True fiber_centered_v_grid = v_auto_grid kw_rv["gaussian_seed_mean_m_s"] = float(v_c) logger.info( "CCF line_mask: auto-center scout (full-order mean CCF) center=%.2f m/s " "n_vel=%d fiber=%s order=%s window_um_scout=%.6f", float(v_c), int(v_auto_grid.size), fiber, order, float(window_um_scout), ) else: v_auto_grid = np.asarray(v_grid_sc, dtype=np.float64) if centered: ( rvs_o, errs_o, centers_o, v_grid_o, ccf_2d, _wl_lo_o, _wl_hi_o, ng_o, _ccf_std_2d, ccf_preview_2d, bis_o, bis_err_o, ) = rv_per_chunks_line_mask( w, s, e, d_bad, mask_lines, window_size_um=window_size_um, v_min_m_s=float(v_min_use), v_max_m_s=float(v_max_use), v_step_m_s=float(v_step_m_s), v_grid_m_s=v_grid, zb=zb, max_cores=max_cores, return_ccf=True, **kw_rv, ) elif v_auto_grid is not None: ( rvs_o, errs_o, centers_o, v_grid_o, ccf_2d, _wl_lo_o, _wl_hi_o, ng_o, _ccf_std_2d, ccf_preview_2d, bis_o, bis_err_o, ) = rv_per_chunks_line_mask( w, s, e, d_bad, mask_lines, window_size_um=window_size_um, v_min_m_s=float(v_min_use), v_max_m_s=float(v_max_use), v_step_m_s=float(v_step_m_s), v_grid_m_s=v_auto_grid, zb=zb, max_cores=max_cores, return_ccf=True, **kw_rv, ) else: ( rvs_o, errs_o, centers_o, v_grid_o, ccf_2d, _wl_lo_o, _wl_hi_o, ng_o, _ccf_std_2d, ccf_preview_2d, bis_o, bis_err_o, ) = rv_per_chunks_line_mask( w, s, e, d_bad, mask_lines, window_size_um=window_size_um, v_min_m_s=v_min_use, v_max_m_s=v_max_use, v_step_m_s=v_step_m_s, zb=zb, max_cores=max_cores, return_ccf=True, **kw_rv, ) rvccf_order_start = len(rvccf_rows_accum) if rvs_o.size != 0: for ii in range(int(rvs_o.size)): order_chunk_rvs.append(float(rvs_o[ii])) ev = float(errs_o[ii]) order_chunk_errs.append(ev if np.isfinite(ev) and ev > 0 else float("nan")) order_chunk_wl.append(float(centers_o[ii])) order_chunk_ng.append(int(ng_o[ii])) if ccf_2d is not None and ccf_2d.size > 0: for ii in range(int(rvs_o.size)): rvccf_rows_accum.append(np.asarray(ccf_2d[ii], dtype=np.float64)) rvccf_n_good_accum.append(int(ng_o[ii])) bv = float(bis_o[ii]) if ii < int(bis_o.size) else float("nan") be = float(bis_err_o[ii]) if ii < int(bis_err_o.size) else float("nan") rvccf_bis_accum.append(bv) rvccf_bis_err_accum.append(be) v_now = np.asarray(v_grid_o, dtype=np.float64) # Stack chunk CCF rows for order-mean RV (same basis as chunk RV / RVCCF HDU). stack_for_order_mean = ccf_2d if order_v_grid is None: order_v_grid = v_now order_ccf_rows.append(stack_for_order_mean) elif order_v_grid.shape == v_now.shape and np.allclose(order_v_grid, v_now): order_ccf_rows.append(stack_for_order_mean) n_chunks_order = len(order_chunk_rvs) if n_chunks_order == 0: continue order_used_gaussian_mean = False stacked_order: np.ndarray | None = None ccf_mean_order: np.ndarray | None = None ccf_err_mean_order: np.ndarray | None = None sigma_hp_order = float("nan") if order_ccf_rows and order_v_grid is not None: stacked_order = np.vstack(order_ccf_rows) ccf_mean_order = _nanmean_axis0_ignore_empty_columns(stacked_order) sigma_hp_order, _, _ = estimate_ccf_uncertainty_highpass_residual(ccf_mean_order) if np.isfinite(sigma_hp_order) and sigma_hp_order > 0.0: ccf_err_mean_order = np.full_like( np.asarray(ccf_mean_order, dtype=np.float64), float(sigma_hp_order), dtype=np.float64, ) else: ccf_err_mean_order = None v_fit = np.asarray(order_v_grid, dtype=np.float64) # Duplicate the order-mean RV onto every chunk row only when this echelle # row has a **single** line-mask chunk. if n_chunks_order == 1: ccf_err_fit: np.ndarray | None = None if ( _ccf_std_2d is not None and np.asarray(_ccf_std_2d).shape[0] == 1 and np.any(np.isfinite(_ccf_std_2d[0])) ): ccf_err_fit = np.asarray(_ccf_std_2d[0], dtype=np.float64) elif ccf_err_mean_order is not None: ccf_err_fit = ccf_err_mean_order _gauss_seed = ( float(ccf_center_m_s) if centered and ccf_center_m_s is not None and math.isfinite(float(ccf_center_m_s)) else ( float(fiber_scout_center_m_s) if order_auto_centered and fiber_scout_center_m_s is not None and math.isfinite(float(fiber_scout_center_m_s)) else None ) ) vstep_fit = float(effective_ccf_v_step_for_fit(v_fit)) wl_c = 0.5 * (w_min + w_max) vsp = dv_per_pixel_m_s(float(wl_c)) n_good_fit = max(int(np.nansum(order_chunk_ng)), 1) rv_g, err_g, _par_g, diag_g = fit_ccf_rv( v_fit, ccf_mean_order, vstep_fit, n_good=n_good_fit, return_params=True, vel_span_m_s_per_pixel=vsp if np.isfinite(vsp) else None, ccf_err=ccf_err_fit, ccf_line_mask_stored_negated=LINE_MASK_CCF_STORED_NEGATED_FROM_RAW, line_mask_line_window_by_line=bool(window_line_by_line), gaussian_seed_mean_m_s=_gauss_seed, ) if ( bool(diag_g.get("fit_ok")) and np.isfinite(rv_g) and np.isfinite(err_g) and float(err_g) > 0.0 ): order_chunk_rvs = [float(rv_g)] * n_chunks_order order_chunk_errs = [float(err_g)] * n_chunks_order order_used_gaussian_mean = True if order_used_gaussian_mean: fiber_agg_rvs.append(float(order_chunk_rvs[0])) fiber_agg_errs.append(float(order_chunk_errs[0])) ai = len(fiber_agg_rvs) - 1 chunk_fiber_agg_index.extend([ai] * n_chunks_order) else: for rv_c, er_c in zip(order_chunk_rvs, order_chunk_errs): fiber_agg_rvs.append(float(rv_c)) fiber_agg_errs.append(float(er_c)) chunk_fiber_agg_index.append(len(fiber_agg_rvs) - 1) all_rvs.extend(order_chunk_rvs) all_rv_errs.extend(order_chunk_errs) all_wavelengths.extend(order_chunk_wl) all_orders.extend([int(order)] * n_chunks_order) # Preview slots: one CCF curve per line-mask chunk (dropdown in stellar RV preview). # When several chunks share an echelle order (line-window Voronoi bins), each chunk # gets its own slot + ``rvccf_chunk_id`` aligned with ``RVCCF`` ``CHUNK_ID``. if want_preview_effective and ccf_2d is not None and n_chunks_order > 0: c2 = np.asarray(ccf_2d, dtype=np.float64) if c2.ndim == 2 and c2.shape[0] == n_chunks_order: v_prev = np.asarray(v_grid_o, dtype=np.float64) std2 = ( np.asarray(_ccf_std_2d, dtype=np.float64) if _ccf_std_2d is not None and np.asarray(_ccf_std_2d).shape == c2.shape else None ) wlo_a = ( np.asarray(_wl_lo_o, dtype=np.float64) if _wl_lo_o is not None else None ) whi_a = ( np.asarray(_wl_hi_o, dtype=np.float64) if _wl_hi_o is not None else None ) ng_arr = np.asarray(ng_o, dtype=np.int64) n_rvccf_added = int(len(rvccf_rows_accum) - rvccf_order_start) have_rvccf_ids = n_rvccf_added == int(n_chunks_order) and int(n_chunks_order) > 0 for ii in range(n_chunks_order): row = np.asarray(c2[ii], dtype=np.float64) slot_payload: dict = { "kind": "order", "order": int(order), "chunk_index": int(ii), "chunk_n": int(n_chunks_order), "v": v_prev, "ccf": row, "wl_lo": float(wlo_a[ii]) if wlo_a is not None and ii < int(wlo_a.size) else float(w_min), "wl_hi": float(whi_a[ii]) if whi_a is not None and ii < int(whi_a.size) else float(w_max), "n_good": max(1, int(ng_arr[ii])) if ii < int(ng_arr.size) else 1, } if have_rvccf_ids: slot_payload["rvccf_chunk_id"] = int(rvccf_order_start + ii) ce_row: np.ndarray | None = None if std2 is not None and np.any(np.isfinite(std2[ii])): ce_row = np.asarray(std2[ii], dtype=np.float64) elif ( n_chunks_order == 1 and ccf_err_mean_order is not None and np.any(np.isfinite(ccf_err_mean_order)) ): ce_row = np.asarray(ccf_err_mean_order, dtype=np.float64) if ce_row is not None: slot_payload["ccf_err"] = ce_row order_slots.append(slot_payload) all_ccf_rows.append(np.ascontiguousarray(c2[ii : ii + 1], dtype=np.float64)) if std2 is not None: all_ccf_err_rows.append( np.ascontiguousarray(std2[ii : ii + 1], dtype=np.float64) ) elif ( n_chunks_order == 1 and ccf_err_mean_order is not None and np.any(np.isfinite(ccf_err_mean_order)) ): all_ccf_err_rows.append( np.asarray(ccf_err_mean_order, dtype=np.float64, ndmin=2) ) else: all_ccf_err_rows.append( np.full((1, int(c2.shape[1])), np.nan, dtype=np.float64) ) if debug_ccf and n_chunks_order > 0: if kw_rv_line_chunking: n_geom_dbg = line_mask_n_chunks_for_order_line_by_line( w, mask_lines, v_center_m_s=float(kw_rv_line_chunking["line_mask_line_chunk_v_center_m_s"]), zb=float(zb), min_good_pixels=int(min_good_pixels), ) else: n_geom_dbg = ccf_order_n_chunks_for_span(span_um, float(window_size_um)) logger.info( "CCF line_mask fiber=%s order=%s: n_chunks_geom=%d n_chunks_out=%d rv_mean~%.1f m/s", fiber, order, int(n_geom_dbg), n_chunks_order, float(np.nanmedian(order_chunk_rvs)), ) all_rvs_arr = np.asarray(all_rvs, dtype=np.float64) all_rv_errs_arr = np.asarray(all_rv_errs, dtype=np.float64) all_wavelengths_arr = np.asarray(all_wavelengths, dtype=np.float64) all_orders_arr = np.asarray(all_orders, dtype=np.int64) if len(all_orders_arr) != len(all_wavelengths_arr): all_orders_arr = np.full(len(all_wavelengths_arr), -1, dtype=np.int64) # Fiber-level RV aggregation (median/MAD + IV mean) is performed by the stellar RV primitive # so that ccf_utils remains a dependency of stellar_rv (and does not import from it). if centered: pv_min = float(v_grid[0]) pv_max = float(v_grid[-1]) pv_step = float(effective_ccf_v_step_for_fit(v_grid)) preview_v_grid = v_grid elif fiber_centered_v_grid is not None: pv_min = float(fiber_centered_v_grid[0]) pv_max = float(fiber_centered_v_grid[-1]) pv_step = float(effective_ccf_v_step_for_fit(fiber_centered_v_grid)) preview_v_grid = fiber_centered_v_grid else: pv_min = float(v_min_use) pv_max = float(v_max_use) pv_step = float(v_step_m_s) preview_v_grid = v_grid preview_detail = None if want_preview_effective and order_slots and all_ccf_rows: logger.info( "CCF line_mask: fiber=%s building preview n_preview_orders=%d", fiber, len(order_slots), ) preview_detail = finalize_ccf_preview_dict( order_slots, all_ccf_rows, preview_v_grid, pv_min, pv_max, pv_step, all_ccf_err_rows if len(all_ccf_err_rows) == len(order_slots) else None, ccf_line_mask_stored_negated=LINE_MASK_CCF_STORED_NEGATED_FROM_RAW, line_mask_line_window_by_line=bool(window_line_by_line), line_mask_gaussian_seed_mean_m_s=( float(ccf_center_m_s) if centered and ccf_center_m_s is not None and math.isfinite(float(ccf_center_m_s)) else ( float(fiber_scout_center_m_s) if fiber_scout_center_m_s is not None and math.isfinite(float(fiber_scout_center_m_s)) else None ) ), ) logger.info( "CCF line_mask: fiber=%s finished n_chunks=%d preview=%s", fiber, len(all_wavelengths_arr), preview_detail is not None, ) n_rvccf = len(rvccf_rows_accum) if n_rvccf > 0: rvccf_tbl = build_rvccf_chunk_supplement( chunk_id=np.arange(n_rvccf, dtype=np.int32), n_good=np.asarray(rvccf_n_good_accum, dtype=np.int32), v_min=pv_min, v_max=pv_max, v_step=pv_step, ccf_2d=np.stack(rvccf_rows_accum, axis=0), bis=np.asarray(rvccf_bis_accum, dtype=np.float64), bis_err=np.asarray(rvccf_bis_err_accum, dtype=np.float64), ) else: rvccf_tbl = build_rvccf_chunk_supplement( chunk_id=np.array([], dtype=np.int32), n_good=np.array([], dtype=np.int32), v_min=pv_min, v_max=pv_max, v_step=pv_step, ccf_2d=np.empty((0, 0), dtype=np.float64), ) return ( all_wavelengths_arr, all_rvs_arr, all_rv_errs_arr, all_orders_arr, preview_detail, rvccf_tbl, )