import numpy as np
from numba import njit
from hispecdrp.utils.physical_constants import C_M_S
__all__ = [
"cubic_spline_build",
"cubic_spline_eval",
"cubic_spline_eval_scalar",
"cubic_spline_eval_scalar_arrays",
"cubic_spline2d_build",
"cubic_spline2d_eval",
"cubic_spline2d_eval_cell",
"cubic_spline2d_eval_grid",
"cubic_spline2d_eval_scalar",
"cubic_spline2d_eval_scalar_arrays",
"doppler_paint_cubic_spline",
]
@njit(cache=True)
def _solve_slopes_not_a_knot(x : np.ndarray, y : np.ndarray):
"""
Return the first derivatives (slopes) k[i] at each knot for a not-a-knot
cubic spline.
Uses the slope (Hermite) formulation. Interior knots give the standard
tridiagonal equations; the not-a-knot end conditions translate into clean
two-term first/last rows, so the whole system is tridiagonal and (for
sensible data) diagonally dominant — solvable by plain Thomas with no
pivoting on arbitrary (irregular) spacing.
Requires n >= 3.
Parameters
----------
x : np.ndarray
1D array of strictly increasing knot locations.
y : np.ndarray
1D array of knot values.
Returns
-------
slopes : np.ndarray
1D array of slopes at each knot.
"""
n = x.shape[0]
h = np.empty(n - 1)
d = np.empty(n - 1) # secant slopes
for i in range(n - 1):
h[i] = x[i + 1] - x[i]
d[i] = (y[i + 1] - y[i]) / h[i]
lo = np.zeros(n)
di = np.zeros(n)
up = np.zeros(n)
rh = np.zeros(n)
# Interior rows (i = 1..n-2):
# h[i]*k[i-1] + 2*(h[i-1]+h[i])*k[i] + h[i-1]*k[i+1]
# = 3*(h[i]*d[i-1] + h[i-1]*d[i])
for i in range(1, n - 1):
lo[i] = h[i]
di[i] = 2.0 * (h[i - 1] + h[i])
up[i] = h[i - 1]
rh[i] = 3.0 * (h[i] * d[i - 1] + h[i - 1] * d[i])
if n == 3:
# Not-a-knot with 3 points => single parabola; its slope system is
# well-defined with the simple natural-like closure that reproduces the
# quadratic. Use end conditions k0 and k2 from the parabola through the
# three points.
# Parabola p(x); slopes at ends:
h0 = h[0]; h1 = h[1]
# second derivative (constant) of the interpolating parabola:
a2 = (d[1] - d[0]) / (h0 + h1)
k0 = d[0] - a2 * h0
k2 = d[1] + a2 * h1
di[0] = 1.0; rh[0] = k0
di[2] = 1.0; rh[2] = k2
else:
# Not-a-knot left: third derivative continuous across x[1].
# Closed form (de Boor):
# k[0]*h[1]*(h[0]+h[1]) ... -> the standard reduced row is
# k0*h1 + k1*(h0+h1) = ((h0+2*(h0+h1))*h1*d0 + h0^2*d1)/(h0+h1)
h0 = h[0]; h1 = h[1]
di[0] = h1
up[0] = h0 + h1
rh[0] = ((h0 + 2.0 * (h0 + h1)) * h1 * d[0] + h0 * h0 * d[1]) / (h0 + h1)
# Not-a-knot right: symmetric across x[n-2].
hm1 = h[n - 2]; hm2 = h[n - 3]
lo[n - 1] = hm2 + hm1
di[n - 1] = hm2
rh[n - 1] = ((hm1 + 2.0 * (hm2 + hm1)) * hm2 * d[n - 2]
+ hm1 * hm1 * d[n - 3]) / (hm2 + hm1)
# Thomas algorithm
cp = np.empty(n)
dp = np.empty(n)
cp[0] = up[0] / di[0]
dp[0] = rh[0] / di[0]
for i in range(1, n):
m = di[i] - lo[i] * cp[i - 1]
if i < n - 1:
cp[i] = up[i] / m
dp[i] = (rh[i] - lo[i] * dp[i - 1]) / m
slopes = np.empty(n)
slopes[n - 1] = dp[n - 1]
for i in range(n - 2, -1, -1):
slopes[i] = dp[i] - cp[i] * slopes[i + 1]
return slopes
@njit(cache=True)
def _coeffs_from_slopes(x : np.ndarray, y : np.ndarray, slopes : np.ndarray):
"""
Convert knot slopes into per-segment (a,b,c,d) Horner coefficients
about the left knot of each segment. n-1 segments.
On segment i with width h and secant slope dd=(y[i+1]-y[i])/h:
a = y[i]
b = slopes[i]
c = (3*dd - 2*slopes[i] - slopes[i+1]) / h
d = (slopes[i] + slopes[i+1] - 2*dd) / h**2
Parameters
----------
x : np.ndarray
1D array of strictly increasing knot locations.
y : np.ndarray
1D array of knot values.
slopes : np.ndarray
1D array of slopes at each knot.
"""
n = x.shape[0]
a = np.empty(n - 1)
b = np.empty(n - 1)
cc = np.empty(n - 1)
d = np.empty(n - 1)
for i in range(n - 1):
h = x[i + 1] - x[i]
dd = (y[i + 1] - y[i]) / h
a[i] = y[i]
b[i] = slopes[i]
cc[i] = (3.0 * dd - 2.0 * slopes[i] - slopes[i + 1]) / h
d[i] = (slopes[i] + slopes[i + 1] - 2.0 * dd) / (h * h)
return a, b, cc, d
[docs]
@njit(cache=True)
def cubic_spline_build(x : np.ndarray, y : np.ndarray):
"""
Build & cache the not-a-knot cubic spline.
Returns a tuple (x, a, b, c, d) — pass this same tuple to the eval funcs.
Call once; reuse for many evaluations.
Parameters
----------
x : np.ndarray
1D array of strictly increasing knot locations.
y : np.ndarray
1D array of knot values.
"""
k = _solve_slopes_not_a_knot(x, y)
a, b, c, d = _coeffs_from_slopes(x, y, k)
return x, a, b, c, d
@njit(cache=True, inline="always")
def _find_segment(xk : np.ndarray, xq : float):
"""Binary search: largest i with xk[i] <= xq, clamped to [0, n-2]."""
n = xk.shape[0]
if xq <= xk[0]:
return 0
if xq >= xk[n - 1]:
return n - 2
lo = 0
hi = n - 1
while hi - lo > 1:
mid = (lo + hi) >> 1
if xk[mid] <= xq:
lo = mid
else:
hi = mid
return lo
[docs]
@njit(cache=True, nogil=True, inline="always")
def cubic_spline_eval_scalar_arrays(
xk: np.ndarray,
a: np.ndarray,
b: np.ndarray,
c: np.ndarray,
d: np.ndarray,
xq: float,
) -> float:
"""Evaluate a spline from unpacked coefficient arrays (Numba-friendly)."""
i = _find_segment(xk, xq)
t = xq - xk[i]
return a[i] + t * (b[i] + t * (c[i] + t * d[i]))
[docs]
@njit(cache=True)
def cubic_spline_eval_scalar(cache : tuple, xq : float):
"""
Evaluate the cached spline at a single scalar point.
Points outside the knot range are extrapolated with the end cubics.
Parameters
----------
cache : tuple
The tuple returned by `cubic_spline_build`.
xq : float
The query point at which to evaluate the spline.
Returns
-------
float
The spline value at the query point.
"""
xk, a, b, c, d = cache
i = _find_segment(xk, xq)
t = xq - xk[i]
return a[i] + t * (b[i] + t * (c[i] + t * d[i]))
[docs]
@njit(cache=True)
def cubic_spline_eval(cache : tuple, xq : np.ndarray):
"""
Evaluate the cached spline at an array of sorted query points.
Points outside the knot range are extrapolated with the end cubics.
Parameters
----------
cache : tuple
The tuple returned by `cubic_spline_build`.
xq : np.ndarray
The query points at which to evaluate the spline.
Returns
-------
np.ndarray
The spline value at the query point.
"""
xk, a, b, c, d = cache
n = xk.shape[0]
m = xq.shape[0]
out = np.empty(m)
i = 0
for k in range(m):
xx = xq[k]
# advance segment pointer while the next knot is still <= xx
while i < n - 2 and xk[i + 1] <= xx:
i += 1
# (no need to walk backwards: xq is sorted ascending)
t = xx - xk[i]
out[k] = a[i] + t * (b[i] + t * (c[i] + t * d[i]))
return out
[docs]
@njit(cache=True)
def cubic_spline2d_build(x : np.ndarray, y : np.ndarray, z : np.ndarray):
"""
Build & cache the tensor-product not-a-knot cubic spline of a 2D grid.
The knot slopes come from the 1D not-a-knot solver: along each row
(d/dx), along each column (d/dy), and along each column of the x-slopes
(d2/dxdy). Together with the values these define a bicubic patch on
every cell, which is exactly the tensor-product spline.
Returns a tuple (x, y, z, zx, zy, zxy) — pass this same tuple to the
2D eval funcs. Call once; reuse for many evaluations.
Requires at least 3 knots along each axis.
Parameters
----------
x : np.ndarray
1D array of strictly increasing knot locations along the columns (length Ncols).
y : np.ndarray
1D array of strictly increasing knot locations along the rows (length Nrows).
z : np.ndarray
2D array of knot values with shape (Nrows, Ncols), z[j, i] at (x[i], y[j]).
"""
Nrows, Ncols = z.shape
zx = np.empty((Nrows, Ncols))
zy = np.empty((Nrows, Ncols))
zxy = np.empty((Nrows, Ncols))
for j in range(Nrows):
zx[j, :] = _solve_slopes_not_a_knot(x, z[j, :].copy())
for i in range(Ncols):
zy[:, i] = _solve_slopes_not_a_knot(y, z[:, i].copy())
zxy[:, i] = _solve_slopes_not_a_knot(y, zx[:, i].copy())
return x, y, z, zx, zy, zxy
@njit(cache=True, nogil=True, inline="always")
def _cubic_from_ends(f0 : float, s0 : float, f1 : float, s1 : float, h : float, t : float):
"""
Cubic through (0, f0) and (h, f1) with end slopes s0 and s1, evaluated at offset t
from the left end. Same Horner coefficients as `_coeffs_from_slopes`, so extrapolation
far outside the segment does not lose precision.
"""
dd = (f1 - f0) / h
c = (3.0 * dd - 2.0 * s0 - s1) / h
d = (s0 + s1 - 2.0 * dd) / (h * h)
return f0 + t * (s0 + t * (c + t * d))
[docs]
@njit(cache=True, nogil=True, inline="always")
def cubic_spline2d_eval_scalar_arrays(
xk: np.ndarray,
yk: np.ndarray,
z: np.ndarray,
zx: np.ndarray,
zy: np.ndarray,
zxy: np.ndarray,
xq: float,
yq: float,
) -> float:
"""Evaluate a 2D spline from unpacked arrays (Numba-friendly)."""
i = _find_segment(xk, xq)
j = _find_segment(yk, yq)
return cubic_spline2d_eval_cell(
z, zx, zy, zxy, i, j, xk[i + 1] - xk[i], yk[j + 1] - yk[j], xq - xk[i], yq - yk[j]
)
[docs]
@njit(cache=True, nogil=True, inline="always")
def cubic_spline2d_eval_cell(
z: np.ndarray,
zx: np.ndarray,
zy: np.ndarray,
zxy: np.ndarray,
i: int,
j: int,
hx: float,
hy: float,
tx: float,
ty: float,
) -> float:
"""
Evaluate a 2D spline (unpacked from `cubic_spline2d_build`) on a known cell (Numba-friendly).
The cell spans knots i, i+1 along x (width hx) and j, j+1 along y (width hy); tx and ty are the
offsets of the query point from knot (i, j). Use this when the cell is known without a search,
e.g. on a uniform grid; offsets outside [0, hx] x [0, hy] extrapolate that cell's bicubic.
"""
# Interpolate values and y-slopes along x on rows j and j+1, then along y
v0 = _cubic_from_ends(z[j, i], zx[j, i], z[j, i + 1], zx[j, i + 1], hx, tx)
v1 = _cubic_from_ends(z[j + 1, i], zx[j + 1, i], z[j + 1, i + 1], zx[j + 1, i + 1], hx, tx)
s0 = _cubic_from_ends(zy[j, i], zxy[j, i], zy[j, i + 1], zxy[j, i + 1], hx, tx)
s1 = _cubic_from_ends(zy[j + 1, i], zxy[j + 1, i], zy[j + 1, i + 1], zxy[j + 1, i + 1], hx, tx)
return _cubic_from_ends(v0, s0, v1, s1, hy, ty)
[docs]
@njit(cache=True)
def cubic_spline2d_eval_scalar(cache : tuple, xq : float, yq : float):
"""
Evaluate the cached 2D spline at a single point.
Points outside the knot range are extrapolated with the end cubics.
Parameters
----------
cache : tuple
The tuple returned by `cubic_spline2d_build`.
xq : float
The query x location.
yq : float
The query y location.
Returns
-------
float
The spline value at the query point.
"""
xk, yk, z, zx, zy, zxy = cache
return cubic_spline2d_eval_scalar_arrays(xk, yk, z, zx, zy, zxy, xq, yq)
[docs]
@njit(cache=True)
def cubic_spline2d_eval(cache : tuple, xq : np.ndarray, yq : np.ndarray):
"""
Evaluate the cached 2D spline at an array of points (xq[k], yq[k]), in any order.
Points outside the knot range are extrapolated with the end cubics.
Parameters
----------
cache : tuple
The tuple returned by `cubic_spline2d_build`.
xq : np.ndarray
1D array of query x locations.
yq : np.ndarray
1D array of query y locations, same length as xq.
Returns
-------
np.ndarray
The spline values at the query points.
"""
xk, yk, z, zx, zy, zxy = cache
m = xq.shape[0]
out = np.empty(m)
for k in range(m):
out[k] = cubic_spline2d_eval_scalar_arrays(xk, yk, z, zx, zy, zxy, xq[k], yq[k])
return out
[docs]
@njit(cache=True)
def cubic_spline2d_eval_grid(cache : tuple, xq : np.ndarray, yq : np.ndarray):
"""
Evaluate the cached 2D spline on the grid of all (xq[i], yq[j]).
Points outside the knot range are extrapolated with the end cubics.
Parameters
----------
cache : tuple
The tuple returned by `cubic_spline2d_build`.
xq : np.ndarray
1D array of query x locations (length Ncols).
yq : np.ndarray
1D array of query y locations (length Nrows).
Returns
-------
np.ndarray
The spline values with shape (Nrows, Ncols), out[j, i] at (xq[i], yq[j]).
"""
xk, yk, z, zx, zy, zxy = cache
out = np.empty((yq.shape[0], xq.shape[0]))
for j in range(yq.shape[0]):
for i in range(xq.shape[0]):
out[j, i] = cubic_spline2d_eval_scalar_arrays(xk, yk, z, zx, zy, zxy, xq[i], yq[j])
return out
[docs]
def doppler_paint_cubic_spline(
wave_obs_um: np.ndarray,
wave_rest_um: np.ndarray,
flux_rest: np.ndarray,
rv_m_s: float,
*,
zb: float = 0.0,
) -> np.ndarray:
"""
Resample a rest-frame spectrum onto an observed wavelength grid via cubic spline.
Uses the same not-a-knot cubic spline as
:func:`~hispecdrp.primitives.utils.ccf.ccf_spline.compute_ccf_spline`
(alternate / research path). For paint that matches the **science**
``ccf_line_mask`` sampler, use
:func:`~hispecdrp.primitives.utils.ccf.ccf_utils.doppler_paint_lagrange`
instead (Numba Lanczos / ``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 (µm), **strictly ascending** (as for one echelle order).
wave_rest_um, flux_rest
Rest-frame knots (µm) 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).
Returns
-------
np.ndarray
Flux on ``wave_obs_um`` (float64).
"""
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 w_rest.size != f_rest.size:
raise ValueError("wave_rest_um and flux_rest must have the same length")
if w_rest.size < 3:
raise ValueError("need at least 3 rest-frame knots for cubic spline")
if w_obs.size and not np.all(np.diff(w_obs) > 0.0):
raise ValueError("wave_obs_um must be strictly ascending")
if not np.all(np.diff(w_rest) > 0.0):
raise ValueError("wave_rest_um must be strictly ascending")
cache = cubic_spline_build(w_rest, f_rest)
beta = (1.0 + float(zb)) / (1.0 + float(rv_m_s) / float(C_M_S))
return cubic_spline_eval(cache, w_obs * beta)