Source code for hispecdrp.primitives.utils.ccf.ccf_rv_content
"""Photon-limited RV content and Doppler wavelength mapping for spectra."""
from __future__ import annotations
import numpy as np
from hispecdrp.utils.physical_constants import C_M_S
from ....utils.parallelization_utils import njit, prange
__all__ = [
"compute_rv_content",
"doppler_shift_from_barycenter",
]
@njit(cache=True, nogil=True)
def _gradient(y: np.ndarray, x: np.ndarray, edge_order: int = 1) -> np.ndarray:
"""
Fast equivalent of ``numpy.gradient(y, x, edge_order=edge_order)`` for 1D arrays
on a (possibly) non-uniform grid.
Interior: second-order non-uniform central differences.
Boundaries:
* ``edge_order=1`` — first-order one-sided (NumPy default)
* ``edge_order=2`` — second-order one-sided (more accurate)
Matches ``numpy.gradient`` to floating-point round-off for the corresponding
``edge_order``.
"""
n = y.shape[0]
out = np.empty(n, dtype=np.float64)
if n == 1:
out[0] = 0.0
return out
if n == 2:
slope = (y[1] - y[0]) / (x[1] - x[0])
out[0] = slope
out[1] = slope
return out
for i in range(1, n - 1):
hs = x[i] - x[i - 1]
hd = x[i + 1] - x[i]
a = -hd / (hs * (hs + hd))
b = (hd - hs) / (hs * hd)
c = hs / (hd * (hs + hd))
out[i] = a * y[i - 1] + b * y[i] + c * y[i + 1]
if edge_order == 1:
out[0] = (y[1] - y[0]) / (x[1] - x[0])
out[n - 1] = (y[n - 1] - y[n - 2]) / (x[n - 1] - x[n - 2])
else:
h0 = x[1] - x[0]
h1 = x[2] - x[1]
out[0] = (
-(2.0 * h0 + h1) / (h0 * (h0 + h1)) * y[0]
+ (h0 + h1) / (h0 * h1) * y[1]
- h0 / (h1 * (h0 + h1)) * y[2]
)
hm1 = x[n - 1] - x[n - 2]
hm2 = x[n - 2] - x[n - 3]
out[n - 1] = (
hm1 / (hm2 * (hm2 + hm1)) * y[n - 3]
- (hm2 + hm1) / (hm2 * hm1) * y[n - 2]
+ (2.0 * hm1 + hm2) / (hm1 * (hm2 + hm1)) * y[n - 1]
)
return out
[docs]
@njit(cache=True, nogil=True, parallel=True)
def doppler_shift_from_barycenter(
wave: np.ndarray,
vel: float,
zb: float,
) -> np.ndarray:
"""
Map rest-frame wavelength(s) to the observed frame at trial velocity ``vel``.
Applies :math:`\\lambda_{\\rm obs} = \\lambda_{\\rm rest} (1 + v/c) / (1 + z_b)`.
``wave`` must be a 1-D ``float64`` array. Non-finite ``zb`` or ``1 + z_b = 0`` are
treated as ``z_b = 0``. The element loop uses ``prange`` so callers can compose this
inside other parallel Numba kernels.
"""
zb_eff = zb
zb1 = 1.0 + zb_eff
if not np.isfinite(zb1) or zb1 == 0.0:
zb_eff = 0.0
factor = (1.0 + vel / C_M_S) / (1.0 + zb_eff)
n = wave.shape[0]
out = np.empty(n, dtype=np.float64)
for i in prange(n):
out[i] = wave[i] * factor
return out
[docs]
@njit(cache=True, nogil=True)
def compute_rv_content(
wave: np.ndarray,
spec: np.ndarray,
spec_err: np.ndarray,
spec_dq: np.ndarray,
) -> tuple[np.ndarray, float]:
"""
Photon-limited RV content per pixel and combined, following Bouchy, Pepe & Queloz (2001).
The RV uncertainty contributed by a single pixel is
.. math::
dV_i = c \\, \\sigma_i / (\\lambda_i \\, |dA_i/d\\lambda|)
where :math:`\\sigma_i` is the flux uncertainty at that pixel.
The combined RV content adds in inverse quadrature over independent pixels:
.. math::
1 / dV_{\\rm tot}^2 = \\sum_i 1 / dV_i^2
Parameters
----------
wave
Wavelength solution (any units; RV content is returned in m/s).
spec
Flux spectrum.
spec_err
1-sigma flux uncertainty per pixel.
spec_dq
Data quality mask (0 = good, nonzero = bad). Bad pixels are excluded.
Returns
-------
rvc_per_pix
Per-pixel RV content :math:`dV_i` (m/s); NaN where the pixel is unusable.
rvc_tot
Combined photon-limited RV uncertainty (m/s).
"""
grad = _gradient(spec, wave)
rvc_per_pix = np.full_like(spec, np.nan, dtype=np.float64)
for i in range(len(spec)):
if spec_dq[i] != 0:
continue
sigma_i = spec_err[i]
d_ai_dw = grad[i]
if not np.isfinite(d_ai_dw) or not np.isfinite(spec[i]):
continue
if not np.isfinite(sigma_i) or sigma_i <= 0.0:
continue
if d_ai_dw == 0.0:
continue
rvc_per_pix[i] = C_M_S * sigma_i / (wave[i] * abs(d_ai_dw))
rvc_tot = np.nansum(1.0 / rvc_per_pix**2) ** (-0.5)
return rvc_per_pix, float(rvc_tot)