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

"""Top-hat (finite-width) mask CCF utilities."""
from __future__ import annotations

import math

import numpy as np

from hispecdrp.utils.physical_constants import C_M_S
from ....utils.parallelization_utils import njit

from .ccf_common import _velocity_grid_from_window

__all__ = [
    "TOPHAT_MASK_CCF_SEGMENT_SAMPLES",
    "compute_ccf_tophat",
]

# Legacy chunk-parallel mask CCF in :func:`~hispecdrp.primitives.utils.ccf.ccf_utils._calc_mask_ccf_chunks_numba`
# approximates finite segments by uniform point samples; retained until that path uses binning.
TOPHAT_MASK_CCF_SEGMENT_SAMPLES = 8


@njit(cache=True, nogil=True)
def _pixel_edges_from_wavelength_numba(wave: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """
    Left/right wavelength edges for each pixel from monotonic centers.

    Interior edges are midpoints between adjacent centers; outer edges mirror the
    first / last pixel spacing outward.
    """
    n = wave.shape[0]
    lo = np.empty(n, dtype=np.float64)
    hi = np.empty(n, dtype=np.float64)
    lo[0] = wave[0] - 0.5 * (wave[1] - wave[0])
    hi[0] = wave[0] + 0.5 * (wave[1] - wave[0])
    for i in range(1, n):
        half = 0.5 * (wave[i] - wave[i - 1])
        lo[i] = wave[i] - half
        hi[i] = wave[i] + half
    return lo, hi


@njit(cache=True, nogil=True)
def _bin_tophat(
    pixel_lo: np.ndarray,
    pixel_hi: np.ndarray,
    tophat_lo: float,
    tophat_hi: float,
    tophat_height: float,
    out: np.ndarray,
) -> tuple[int, int]:
    """
    Bin a top hat onto discrete pixel edges with area normalization.

    The binned values sum to ``tophat_height`` (the line weight).

    Returns
    -------
    i_start, i_stop
        Inclusive pixel index range written, or ``(0, -1)`` when there is no overlap.
    """
    if tophat_hi <= pixel_lo[0] or tophat_lo >= pixel_hi[-1]:
        return 0, -1

    i_start = int(np.searchsorted(pixel_hi, tophat_lo, side="right"))
    i_stop = int(np.searchsorted(pixel_lo, tophat_hi, side="left")) - 1
    if i_stop < i_start:
        return 0, -1

    total = 0.0
    for i in range(i_start, i_stop + 1):
        lo = pixel_lo[i] if pixel_lo[i] > tophat_lo else tophat_lo
        hi = pixel_hi[i] if pixel_hi[i] < tophat_hi else tophat_hi
        overlap = hi - lo
        if overlap > 0.0:
            out[i] = overlap
            total += overlap

    if total > 0.0:
        scale = tophat_height / total
        for i in range(i_start, i_stop + 1):
            out[i] *= scale

    return i_start, i_stop


@njit(cache=True, nogil=True)
def _compute_ccf_tophat(
    wave: np.ndarray,
    spec: np.ndarray,
    spec_err: np.ndarray,
    spec_dq: np.ndarray,
    line_centers: np.ndarray,
    line_weights: np.ndarray,
    tophat_width_m_s: float,
    vel_grid: np.ndarray,
    zb: float,
    ccf_out: np.ndarray,
    ccf_err_out: np.ndarray,
) -> None:
    """
    Numba core for :func:`compute_ccf_tophat`.

    Each line is a rest-frame top hat with constant velocity width ``tophat_width_m_s``,
    Doppler-shifted per trial velocity and binned onto pixel edges.
    """
    n_pix = spec.shape[0]
    n_vels = vel_grid.shape[0]
    n_lines = line_centers.shape[0]

    tophat_weights = np.zeros(n_pix, dtype=np.float64)
    half_width_frac = 0.5 * tophat_width_m_s / C_M_S
    pixel_lo, pixel_hi = _pixel_edges_from_wavelength_numba(wave)

    for idx_vel in range(n_vels):
        vel = vel_grid[idx_vel]
        sh = (1.0 + vel / C_M_S) / (1.0 + zb)
        ccf = 0.0
        ccf_var = 0.0
        w_total = 0.0

        for idx_line in range(n_lines):
            line_center = line_centers[idx_line]
            line_weight = line_weights[idx_line]

            if not np.isfinite(line_center) or line_center <= 0.0:
                continue
            if not np.isfinite(line_weight) or line_weight <= 0.0:
                continue

            tophat_lo = line_center * (1.0 - half_width_frac) * sh
            tophat_hi = line_center * (1.0 + half_width_frac) * sh

            i_start, i_stop = _bin_tophat(
                pixel_lo,
                pixel_hi,
                tophat_lo,
                tophat_hi,
                line_weight,
                tophat_weights,
            )
            if i_stop < i_start:
                continue

            bad = False
            for i in range(i_start, i_stop + 1):
                if spec_dq[i] != 0:
                    bad = True
                    break
            if bad:
                for i in range(i_start, i_stop + 1):
                    tophat_weights[i] = 0.0
                continue

            for i in range(i_start, i_stop + 1):
                t_weight = tophat_weights[i]
                if t_weight == 0.0:
                    continue
                flux = spec[i]
                var = spec_err[i] * spec_err[i]
                if not np.isfinite(flux) or not np.isfinite(var) or var <= 0.0:
                    continue
                inv_var = t_weight / var
                ccf += flux * inv_var
                ccf_var += inv_var * inv_var * var
                w_total += inv_var

            for i in range(i_start, i_stop + 1):
                tophat_weights[i] = 0.0

        if w_total > 0.0:
            ccf_out[idx_vel] = ccf / w_total
            ccf_err_out[idx_vel] = math.sqrt(ccf_var) / w_total
        else:
            ccf_out[idx_vel] = np.nan
            ccf_err_out[idx_vel] = np.nan


[docs] def compute_ccf_tophat( wave: np.ndarray, spec: np.ndarray, spec_err: np.ndarray, spec_dq: np.ndarray, line_centers: np.ndarray, line_weights: np.ndarray, tophat_width: float, vel_window: float, vel_step: float, zb: float = 0.0, vsys: float = 0.0, ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """ Cross-correlation of a spectrum with a velocity-width top-hat line mask. Each mask line is a rest-frame segment with constant velocity width ``tophat_width`` (m/s full width). At trial velocity ``v`` the segment is Doppler-mapped as :math:`\\lambda_{\\rm obs} = \\lambda_{\\rm rest}(1+v/c)/(1+z_b)` and binned onto detector pixel edges (area-preserving). The CCF at each velocity is an inverse-variance weighted mean flux under the combined mask. Parameters ---------- wave Monotonic wavelength centers (µm or any consistent unit). spec, spec_err Flux and 1-sigma uncertainty per pixel. spec_dq Data-quality flags (0 = good, nonzero = bad). line_centers, line_weights Rest-frame line centers and weights. tophat_width Full width of each top hat in m/s (rest frame). vel_window Total velocity span of the output grid (m/s). vel_step Uniform velocity step (m/s). zb Barycentric factor :math:`z_b` (dimensionless). vsys Systemic velocity (m/s) at the center of ``vel_window``. Returns ------- vel_grid, ccf, ccf_err Trial velocities (m/s), CCF value, and formal uncertainty per velocity sample. """ wave = np.asarray(wave, dtype=np.float64).ravel() spec = np.asarray(spec, dtype=np.float64).ravel() spec_err = np.asarray(spec_err, dtype=np.float64).ravel() spec_dq = np.asarray(spec_dq).ravel() line_centers = np.asarray(line_centers, dtype=np.float64).ravel() line_weights = np.asarray(line_weights, dtype=np.float64).ravel() vel_grid = _velocity_grid_from_window(vel_window, vel_step, vsys) n_vels = vel_grid.size ccf_out = np.full(n_vels, np.nan, dtype=np.float64) ccf_err_out = np.full(n_vels, np.nan, dtype=np.float64) _compute_ccf_tophat( wave, spec, spec_err, spec_dq, line_centers, line_weights, float(tophat_width), vel_grid, float(zb), ccf_out, ccf_err_out, ) return vel_grid, ccf_out, ccf_err_out