nufftcf 0.1.0__py3-none-any.whl

nufftcf/__init__.py

@@ -0,0 +1,89 @@
+"""
+nufftcf: fast ACF estimation for irregularly- AND regularly-sampled time series.
+
+Three estimation families are provided, sharing the same (lags, t, x, bin_width)
+calling convention:
+
+- `compute_acf_*_nufft`      : NUFFT + Wiener-Khinchin, O(n log n)-ish, fastest
+                                for long IRREGULAR series, ~1-3% residual
+                                amplitude bias on strongly periodic signals
+                                (see module docs).
+- `compute_acf_*_realspace`  : direct real-space weighted sum, O(n) per lag,
+                                artifact-free reference / alternative, works
+                                for irregular AND regular sampling.
+- `compute_acf_*_fft`        : classic FFT correlation, O(n log n), for
+                                REGULARLY-sampled data only -- faster than
+                                `_nufft` (no NUFFT overhead) and faster than
+                                `_realspace` (no numba two-pointer scan) when
+                                sampling happens to be regular. Also adds a
+                                `regular` (no-kernel) variant matching
+                                Pastas' `bin_method="regular"`.
+
+All families come in `gaussian` and `rectangle` kernel variants; `_fft` also
+has `regular` (no smoothing kernel).
+
+Example
+-------
+>>> import numpy as np, pandas as pd
+>>> from nufftcf import compute_acf_gaussian_nufft, t_numeric_of
+>>> idx = pd.date_range("2020-01-01", periods=2000, freq="D")
+>>> x = pd.Series(np.random.randn(2000), index=idx)
+>>> lags = np.arange(0.0, 366.0)
+>>> t = t_numeric_of(x)
+>>> c, b = compute_acf_gaussian_nufft(lags, t, x.to_numpy(), bin_width=0.5)
+
+>>> # regularly-sampled data -> use the faster classic-FFT path instead:
+>>> from nufftcf import compute_acf_gaussian_fft, compute_acf_regular_fft
+>>> c, b = compute_acf_gaussian_fft(lags, t, x.to_numpy(), bin_width=0.5)
+>>> c, b = compute_acf_regular_fft(lags, t, x.to_numpy())  # no kernel
+"""
+
+from .kernels import (
+    compute_b_gaussian,
+    compute_b_rectangle,
+    compute_c_gaussian,
+    compute_c_rectangle,
+)
+from .nufft_acf import compute_acf_gaussian_nufft, compute_acf_rectangle_nufft
+from .realspace_acf import (
+    compute_acf_gaussian_realspace,
+    compute_acf_rectangle_realspace,
+)
+from .nufft_ccf import compute_ccf_gaussian_nufft, compute_ccf_rectangle_nufft
+from .realspace_ccf import (
+    compute_ccf_gaussian_realspace,
+    compute_ccf_rectangle_realspace,
+)
+
+from .fft_acf import (
+    compute_acf_regular_fft,
+    compute_acf_rectangle_fft,
+    compute_acf_gaussian_fft,
+)
+from .utils import t_numeric_of, standardize
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "compute_acf_gaussian_nufft",
+    "compute_acf_rectangle_nufft",
+    "compute_acf_gaussian_realspace",
+    "compute_acf_rectangle_realspace",
+    "compute_acf_regular_fft",
+    "compute_acf_rectangle_fft",
+    "compute_acf_gaussian_fft",
+    "compute_ccf_gaussian_nufft",
+    "compute_ccf_rectangle_nufft",
+    "compute_ccf_gaussian_realspace",
+    "compute_ccf_rectangle_realspace",
+    "compute_b_gaussian",
+    "compute_b_rectangle",
+    "compute_c_gaussian",
+    "compute_c_rectangle",
+    "compute_b_gaussian_cross",
+    "compute_b_rectangle_cross",
+    "compute_c_gaussian_cross",
+    "compute_c_rectangle_cross",
+    "t_numeric_of",
+    "standardize",
+]

nufftcf/fft_acf.py

@@ -0,0 +1,221 @@
+"""
+ACF estimation for REGULARLY-sampled series, via classic FFT correlation
+(`scipy.signal.correlate`) instead of NUFFT.
+
+This is a fast-path companion to `nufft_acf.py` / `realspace_acf.py`: when
+the data happens to be on a uniform grid, there is no need to pay for NUFFT
+(or for the O(n)-per-lag numba two-pointer scan) -- a plain FFT correlation
+plus a cheap smoothing pass gives the *exact same* gaussian/rectangle
+estimator, faster and with no numba/finufft dependency in the hot path.
+
+Three estimators are provided, all sharing the same (lags, t, x) calling
+convention as the rest of the package:
+
+- `compute_acf_regular_fft`   : no smoothing kernel at all -- the windowed
+                                 Pearson correlation Pastas uses for its
+                                 "regular" bin_method (regular data only).
+                                 Scales ~O(n) (it is NOT a quadratic method,
+                                 unlike Pastas' gaussian/rectangle bin
+                                 methods -- see benchmark/).
+- `compute_acf_rectangle_fft` : same rectangular-kernel definition as
+                                 `compute_acf_rectangle_nufft`/`_realspace`.
+- `compute_acf_gaussian_fft`  : same gaussian-kernel definition as
+                                 `compute_acf_gaussian_nufft`/`_realspace`.
+
+All three require `t` to be regularly spaced (checked, raises otherwise);
+use the `nufft` or `realspace` estimators for irregular sampling.
+
+Implementation note on the `b` (pair-count) denominator
+---------------------------------------------------------
+For `gaussian`, `b` is obtained by applying the *exact same* smoothing
+filter (`gaussian_filter1d`, same sigma, same boundary mode) to the
+triangular "raw pair count" ramp `n - |lag|` as is applied to the raw
+correlation numerator. This isn't just convenient: computing numerator and
+denominator through the same discrete kernel makes any discretization
+artifact of that kernel cancel exactly in the ratio, which is what lets
+this estimator match `compute_acf_gaussian_realspace` to ~1e-6 without any
+extra renormalization step. `mode="mirror"` is required (not scipy's
+default `"reflect"`) for this cancellation to hold all the way to lag=0,
+since the true pair-count ramp is symmetric *through* lag=0 (whole-sample
+symmetry), not around the edge *between* lag=-1 and lag=0 (half-sample
+symmetry, which is what `"reflect"` assumes).
+
+For `rectangle`, the unsmoothed ramp `b = n - lag` is already exact as-is
+-- no filtering needed -- because `uniform_filter1d` already normalizes by
+its own window size internally.
+"""
+
+import numpy as np
+from scipy.signal import correlate
+from scipy.ndimage import gaussian_filter1d, uniform_filter1d
+
+from .utils import standardize
+
+
+def _check_regular_grid(t):
+    t = np.asarray(t, dtype=float)
+    if len(t) < 2:
+        return 1.0
+    dt = np.diff(t)
+    dt0 = dt[0]
+    if not np.allclose(dt, dt0, rtol=1e-6):
+        raise ValueError(
+            "compute_acf_*_fft requires a regularly-sampled `t` "
+            "(use the `nufft` or `realspace` estimators for irregular data)."
+        )
+    return dt0
+
+
+def compute_acf_regular_fft(lags, t, x):
+    """ACF estimate with no smoothing kernel, for regularly-sampled data --
+    matches Pastas' `bin_method="regular"` (windowed Pearson correlation)
+    to numerical precision, but vectorized instead of one `np.corrcoef`
+    call per lag.
+
+    Parameters
+    ----------
+    lags : array_like
+        Lags at which to evaluate the ACF (same units as `t`).
+    t : array_like
+        Regularly-spaced sample times, sorted ascending.
+    x : array_like
+        Sample values, same length as `t`.
+
+    Returns
+    -------
+    c, b : ndarray
+        ACF estimate and pair count, both shape (len(lags),).
+    """
+    t = np.asarray(t, dtype=float)
+    x = np.asarray(x, dtype=float)
+    lags = np.asarray(lags, dtype=float)
+    dt = _check_regular_grid(t)
+    n = len(x)
+
+    lag_idx = np.round(lags / dt).astype(int)
+    b = np.where(n - lag_idx <= 0, 1e-16, (n - lag_idx).astype(float))
+
+    # Cumulative first/second moments -> exact windowed mean & std in O(1)
+    # per lag (this is the *exact* expansion Var = E[x^2] - E[x]^2, not an
+    # incremental re-centered sum -- the latter looks similar but silently
+    # drifts by ~0.1-0.3% away from a true windowed std).
+    s1 = np.concatenate(([0.0], np.cumsum(x)))
+    s2 = np.concatenate(([0.0], np.cumsum(x * x)))
+
+    def _windowed_mean_std(lo, hi):
+        cnt = np.maximum((hi - lo).astype(float), 1.0)
+        mean = (s1[hi] - s1[lo]) / cnt
+        var = np.maximum((s2[hi] - s2[lo]) / cnt - mean**2, 0.0)
+        return mean, np.sqrt(var)
+
+    n_lags = len(lag_idx)
+    hi_y = np.clip(n - lag_idx, 0, n)
+    lo_x = np.clip(lag_idx, 0, n)
+    y_mean, y_std = _windowed_mean_std(np.zeros(n_lags, dtype=int), hi_y)
+    x_mean, x_std = _windowed_mean_std(lo_x, np.full(n_lags, n))
+
+    c_raw = correlate(x, x, mode="full")[n - 1 : 2 * n - 1]
+    valid = (lag_idx >= 0) & (lag_idx < n)
+    c_raw_at = np.where(valid, c_raw[np.clip(lag_idx, 0, n - 1)], np.nan)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        cov = (
+            c_raw_at / np.where(n - lag_idx > 0, n - lag_idx, np.nan) - y_mean * x_mean
+        )
+        denom = y_std * x_std
+        c = np.where(denom > 1e-12, cov / denom, np.nan)
+    c = np.where(valid, c, np.nan)
+    return c, b
+
+
+def compute_acf_rectangle_fft(lags, t, x, bin_width=0.5):
+    """ACF estimate via FFT correlation + rectangular smoothing, for
+    regularly-sampled data. Same kernel definition (and -- on the same
+    data -- numerically equivalent result) as `compute_acf_rectangle_nufft`
+    / `compute_acf_rectangle_realspace`, just computed via plain FFT
+    correlation instead of NUFFT / a numba two-pointer scan.
+
+    Parameters
+    ----------
+    lags : array_like
+    t : array_like
+        Regularly-spaced sample times, sorted ascending.
+    x : array_like
+    bin_width : float
+        Rectangular half-width (same units as `t`).
+
+    Returns
+    -------
+    c, b : ndarray
+    """
+    t = np.asarray(t, dtype=float)
+    x = standardize(np.asarray(x, dtype=float))
+    lags = np.asarray(lags, dtype=float)
+    dt = _check_regular_grid(t)
+    n = len(x)
+
+    lag_idx = np.round(lags / dt).astype(int)
+    # Forcing an ODD kernel size (2*k+1) is deliberate.
+    # scipy's uniform_filter1d centers an EVEN-sized window a half
+    # -sample off from the true symmetric [-bin_width, +bin_width] interval
+    # kernels.py's two-pointer scan evaluates exactly, which otherwise
+    # introduces a small but systematic (~0.3-0.5%, not just at lag=0)
+    # bias at every lag -- confirmed empirically, see tests/test_fft_acf.py.
+    kernel_size = 2 * int(round(bin_width / dt)) + 1
+
+    c_raw = correlate(x, x, mode="full")[n - 1 : 2 * n - 1]
+    c_smoothed = uniform_filter1d(c_raw, size=kernel_size, mode="nearest")
+
+    valid = (lag_idx >= 0) & (lag_idx < n)
+    c_at = np.where(valid, c_smoothed[np.clip(lag_idx, 0, n - 1)], np.nan)
+    b = np.where(valid, np.maximum(n - lag_idx, 1e-16), 1e-16)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        c = c_at / b
+    return c, b
+
+
+def compute_acf_gaussian_fft(lags, t, x, bin_width=0.5):
+    """ACF estimate via FFT correlation + gaussian smoothing, for
+    regularly-sampled data. Same kernel definition as
+    `compute_acf_gaussian_nufft` / `compute_acf_gaussian_realspace`.
+
+    Parameters
+    ----------
+    lags : array_like
+    t : array_like
+        Regularly-spaced sample times, sorted ascending.
+    x : array_like
+    bin_width : float
+        Gaussian standard deviation (same units as `t`).
+
+    Returns
+    -------
+    c, b : ndarray
+    """
+    t = np.asarray(t, dtype=float)
+    x = standardize(np.asarray(x, dtype=float))
+    lags = np.asarray(lags, dtype=float)
+    dt = _check_regular_grid(t)
+    n = len(x)
+    sigma = bin_width / dt
+
+    lag_idx = np.round(lags / dt).astype(int)
+    max_idx = int(np.max(np.abs(lag_idx))) if len(lag_idx) else 0
+    n_eval = max(n, max_idx + 1)
+
+    c_raw = correlate(x, x, mode="full")[n - 1 : 2 * n - 1]
+    c_raw = np.pad(c_raw, (0, max(0, n_eval - n)), constant_values=0.0)
+    c_smoothed = gaussian_filter1d(c_raw, sigma=sigma, mode="mirror")
+
+    b_raw = np.maximum(n - np.arange(n_eval, dtype=float), 0.0)
+    b_smoothed = gaussian_filter1d(b_raw, sigma=sigma, mode="mirror")
+
+    valid = (lag_idx >= 0) & (lag_idx < n)
+    idx = np.clip(lag_idx, 0, n_eval - 1)
+    c_at = np.where(valid, c_smoothed[idx], np.nan)
+    b_at = np.where(valid, b_smoothed[idx], 1e-16)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        c = c_at / b_at
+    return c, b_at

nufftcf/kernels.py

@@ -0,0 +1,265 @@
+"""
+Numba-jitted, two-pointer-optimized kernels.
+
+All functions here require `t` (time, in days) sorted in ascending order.
+Complexity is O(n) per lag (instead of the naive O(n^2)), thanks to the
+two-pointer technique: as the lag-shifted window center increases
+monotonically with j (since t is sorted), the window bounds [lo, hi) only
+ever advance, never retreat.
+
+`b_*` functions compute the kernel-weighted (or counted) number of
+contributing pairs per lag -- the normalization denominator.
+
+`c_*` functions compute the kernel-weighted sum of x_i * x_j per lag -- the
+correlation numerator, for the "real-space" (exact, non-NUFFT) ACF estimator.
+"""
+
+import math
+import numpy as np
+from numba import njit, prange
+
+
+@njit(parallel=True, nogil=True, cache=True, fastmath=True)
+def compute_b_gaussian(t, lags, sigma):
+    """Gaussian-kernel weighted pair count per lag."""
+    n = len(t)
+    nlags = len(lags)
+    b = np.zeros(nlags)
+    den1 = -2 * sigma**2
+    den2 = math.sqrt(2 * math.pi) * sigma
+    six_den2 = 6 * den2
+    for k in prange(nlags):
+        lag = lags[k]
+        b_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n):
+            center = t[j] + lag
+            while lo < n and t[lo] < center - six_den2:
+                lo += 1
+            while hi < n and t[hi] < center + six_den2:
+                hi += 1
+            for i in range(lo, hi):
+                dtlag = t[i] - center
+                b_sum += math.exp(dtlag**2 / den1) / den2
+        b[k] = b_sum
+        if b[k] <= 0:
+            b[k] = 1e-16
+    return b
+
+
+@njit(parallel=True, nogil=True, cache=True)
+def compute_b_rectangle(t, lags, bin_width):
+    """Rectangular-kernel pair count per lag (direct count, no inner loop)."""
+    n = len(t)
+    nlags = len(lags)
+    b = np.zeros(nlags)
+    for k in prange(nlags):
+        lag = lags[k]
+        b_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n):
+            center = t[j] + lag
+            while lo < n and t[lo] < center - bin_width:
+                lo += 1
+            if hi < lo:
+                hi = lo
+            while hi < n and t[hi] <= center + bin_width:
+                hi += 1
+            b_sum += hi - lo
+        b[k] = b_sum
+        if b[k] <= 0:
+            b[k] = 1e-16
+    return b
+
+
+@njit(parallel=True, nogil=True, cache=True, fastmath=True)
+def compute_c_gaussian(t, lags, x, sigma):
+    """Gaussian-kernel weighted sum of x_i*x_j per lag (correlation numerator)."""
+    n = len(t)
+    nlags = len(lags)
+    c = np.zeros(nlags)
+    den1 = -2 * sigma**2
+    den2 = math.sqrt(2 * math.pi) * sigma
+    six_den2 = 6 * den2
+    for k in prange(nlags):
+        lag = lags[k]
+        c_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n):
+            center = t[j] + lag
+            while lo < n and t[lo] < center - six_den2:
+                lo += 1
+            while hi < n and t[hi] < center + six_den2:
+                hi += 1
+            xj = x[j]
+            for i in range(lo, hi):
+                dtlag = t[i] - center
+                w = math.exp(dtlag**2 / den1) / den2
+                c_sum += w * x[i] * xj
+        c[k] = c_sum
+    return c
+
+
+@njit(parallel=True, nogil=True, cache=True)
+def compute_c_rectangle(t, lags, x, bin_width):
+    """Rectangular-kernel sum of x_i*x_j per lag, via prefix sums (O(1) per j,
+    since the rectangle kernel weight is uniform inside the window: the
+    window sum of x is looked up directly from a precomputed cumulative sum,
+    rather than re-summed element by element)."""
+    n = len(t)
+    nlags = len(lags)
+    c = np.zeros(nlags)
+    cumsum_x = np.zeros(n + 1)
+    for idx in range(n):
+        cumsum_x[idx + 1] = cumsum_x[idx] + x[idx]
+    for k in prange(nlags):
+        lag = lags[k]
+        c_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n):
+            center = t[j] + lag
+            while lo < n and t[lo] < center - bin_width:
+                lo += 1
+            if hi < lo:
+                hi = lo
+            while hi < n and t[hi] <= center + bin_width:
+                hi += 1
+            window_sum = cumsum_x[hi] - cumsum_x[lo]
+            c_sum += x[j] * window_sum
+        c[k] = c_sum
+    return c
+
+
+# ── Cross-correlation kernel functions ────────────────────────────────────────
+# Same two-pointer logic as the ACF kernels above, adapted for two DIFFERENT
+# time arrays t (for signal x) and s (for signal y).  The CCF pair condition
+# is  s_j - t_i ≈ lag  (whereas for ACF it was  t_i - t_j ≈ lag).
+# As j increases (s[j] increases), center = s[j] - lag increases
+# monotonically, so lo/hi over t still only advance → O(n_t + n_s) per lag.
+
+
+@njit(parallel=True, nogil=True, cache=True, fastmath=True)
+def compute_b_gaussian_cross(t, s, lags, sigma):
+    """Gaussian-kernel weighted pair count for CCF.
+
+    Counts pairs (t_i, s_j) with s_j − t_i ≈ lag, weighted by the
+    Gaussian kernel.  `t` and `s` must both be sorted ascending.
+    """
+    n_t = len(t)
+    n_s = len(s)
+    nlags = len(lags)
+    b = np.zeros(nlags)
+    den1 = -2 * sigma**2
+    den2 = math.sqrt(2 * math.pi) * sigma
+    six_den2 = 6 * den2
+    for k in prange(nlags):
+        lag = lags[k]
+        b_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n_s):
+            center = s[j] - lag  # t_i near here → s_j − t_i ≈ lag
+            while lo < n_t and t[lo] < center - six_den2:
+                lo += 1
+            while hi < n_t and t[hi] < center + six_den2:
+                hi += 1
+            for i in range(lo, hi):
+                dtlag = t[i] - center
+                b_sum += math.exp(dtlag**2 / den1) / den2
+        b[k] = b_sum if b_sum > 0 else 1e-16
+    return b
+
+
+@njit(parallel=True, nogil=True, cache=True)
+def compute_b_rectangle_cross(t, s, lags, bin_width):
+    """Rectangle-kernel pair count for CCF.
+
+    Counts pairs (t_i, s_j) with |s_j − t_i − lag| ≤ bin_width.
+    """
+    n_t = len(t)
+    n_s = len(s)
+    nlags = len(lags)
+    b = np.zeros(nlags)
+    for k in prange(nlags):
+        lag = lags[k]
+        b_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n_s):
+            center = s[j] - lag
+            while lo < n_t and t[lo] < center - bin_width:
+                lo += 1
+            if hi < lo:
+                hi = lo
+            while hi < n_t and t[hi] <= center + bin_width:
+                hi += 1
+            b_sum += hi - lo
+        b[k] = b_sum if b_sum > 0 else 1e-16
+    return b
+
+
+@njit(parallel=True, nogil=True, cache=True, fastmath=True)
+def compute_c_gaussian_cross(t, x, s, y, lags, sigma):
+    """Gaussian-kernel weighted sum of x_i * y_j for CCF.
+
+    For each lag, accumulates x(t_i) * y(s_j) for pairs where
+    s_j − t_i ≈ lag, weighted by the Gaussian kernel w(s_j − t_i − lag).
+    """
+    n_t = len(t)
+    n_s = len(s)
+    nlags = len(lags)
+    c = np.zeros(nlags)
+    den1 = -2 * sigma**2
+    den2 = math.sqrt(2 * math.pi) * sigma
+    six_den2 = 6 * den2
+    for k in prange(nlags):
+        lag = lags[k]
+        c_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n_s):
+            center = s[j] - lag
+            while lo < n_t and t[lo] < center - six_den2:
+                lo += 1
+            while hi < n_t and t[hi] < center + six_den2:
+                hi += 1
+            yj = y[j]
+            for i in range(lo, hi):
+                dtlag = t[i] - center
+                w = math.exp(dtlag**2 / den1) / den2
+                c_sum += w * x[i] * yj
+        c[k] = c_sum
+    return c
+
+
+@njit(parallel=True, nogil=True, cache=True)
+def compute_c_rectangle_cross(t, x, s, y, lags, bin_width):
+    """Rectangle-kernel sum of x_i * y_j for CCF, via prefix sums."""
+    n_t = len(t)
+    n_s = len(s)
+    nlags = len(lags)
+    c = np.zeros(nlags)
+    cumsum_x = np.zeros(n_t + 1)
+    for idx in range(n_t):
+        cumsum_x[idx + 1] = cumsum_x[idx] + x[idx]
+    for k in prange(nlags):
+        lag = lags[k]
+        c_sum = 0.0
+        lo = 0
+        hi = 0
+        for j in range(n_s):
+            center = s[j] - lag
+            while lo < n_t and t[lo] < center - bin_width:
+                lo += 1
+            if hi < lo:
+                hi = lo
+            while hi < n_t and t[hi] <= center + bin_width:
+                hi += 1
+            window_sum = cumsum_x[hi] - cumsum_x[lo]
+            c_sum += y[j] * window_sum
+        c[k] = c_sum
+    return c

nufftcf/nufft_acf.py

@@ -0,0 +1,118 @@
+"""
+ACF estimation via NUFFT (non-uniform FFT) + Wiener-Khinchin theorem.
+
+These estimators compute the power spectrum of the (irregularly-sampled)
+signal via a type-1 NUFFT, then evaluate the implied autocorrelation at the
+requested lags via a type-2 NUFFT. This scales roughly as O(n log n),
+dramatically faster than the O(n^2) real-space approach for long series --
+but it carries a small, known limitation (see README): because it relies on
+a finite-domain Fourier representation, irregular/gappy sampling acts as a
+"spectral window" that slightly distorts narrowband (e.g. periodic) signals
+more than broadband ones. Empirically this is a ~1-3% relative bias in the
+ACF amplitude once N1 is large enough (see N1 note below); for an
+artifact-free reference, use the `realspace` module instead.
+
+`N1 = 32 * n` was empirically validated (against the exact real-space
+estimator) to bring the NUFFT result into close agreement for both gaussian
+and rectangle kernels; pushing higher  gives a marginal further
+improvement for gaussian on strongly periodic signals, at negligible extra
+cost.
+"""
+
+import numpy as np
+import finufft
+from scipy.ndimage import gaussian_filter1d, uniform_filter1d
+
+from .kernels import compute_b_gaussian, compute_b_rectangle
+from .utils import standardize
+
+
+def _nufft_power_spectrum_at_lags(t, x, lags, N1, eps):
+    """Shared first stage: NUFFT type-1 (time -> frequency) then type-2
+    (frequency -> [0.0] + lags), implementing Wiener-Khinchin. Always
+    evaluates an extra point at lag=0 (regardless of whether 0 is already
+    in `lags`), used downstream to normalize the result -- the NUFFT pipeline
+    has its own internal scale convention that has nothing to do with the
+    `b` denominator's scale, so dividing by `b` alone does *not* yield a
+    properly normalized correlation in [-1, 1]. Returns the raw (unsmoothed)
+    correlation at [0.0] + lags, i.e. length len(lags) + 1.
+    """
+    x_normalized = standardize(x)
+    xc = np.complex128(x_normalized)
+    n = len(xc)
+    t_min, t_max = t.min(), t.max()
+    t_norm = (t - t_min) / (t_max - t_min) * (2 * np.pi)
+    lags_norm = (lags - 0) / (t_max - t_min) * (2 * np.pi)
+    if N1 is None:
+        N1 = 32 * n
+    f1 = finufft.nufft1d1(t_norm, xc, (N1,), eps=eps)
+    mul = f1 * np.conj(f1)
+    c_positive = finufft.nufft1d2(lags_norm, mul, eps=eps).real
+    return c_positive  # index 0 is lag=0, indices [1:] correspond to `lags`
+
+
+def compute_acf_gaussian_nufft(lags, t, x, bin_width=0.5, N1=None, eps=1e-9):
+    """ACF estimate via NUFFT + gaussian smoothing.
+
+    Parameters
+    ----------
+    lags : array_like
+        Lags at which to evaluate the ACF (same units as `t`, typically days).
+    t : array_like
+        Sample times, sorted ascending (same units as `lags`).
+    x : array_like
+        Sample values, same length as `t`.
+    bin_width : float
+        Gaussian kernel standard deviation (same units as `t`).
+    N1 : int, optional
+        NUFFT frequency-grid size. Defaults to 32*len(x) in  _nufft_power_spectrum_at_lags
+    eps : float
+        NUFFT requested precision.
+
+    Returns
+    -------
+    c, b : ndarray
+        ACF estimate and effective pair count, both shape (len(lags),).
+    """
+    t = np.asarray(t, dtype=float)
+    x = np.asarray(x, dtype=float)
+    lags = np.asarray(lags, dtype=float)
+    lags_eval = np.concatenate(([0.0], lags))
+
+    c_positive = _nufft_power_spectrum_at_lags(t, x, lags_eval, N1, eps)
+    c_smoothed = gaussian_filter1d(c_positive, sigma=bin_width)
+    b_eval = compute_b_gaussian(t, lags_eval, bin_width)
+    with np.errstate(divide="ignore", invalid="ignore", over="ignore"):
+        c_eval = c_smoothed / b_eval
+    c = c_eval[1:] / c_eval[0]  # normalize by the (always computed) lag=0 value
+    b = b_eval[1:]
+    return c, b
+
+
+def compute_acf_rectangle_nufft(lags, t, x, bin_width=0.5, N1=None, eps=1e-9):
+    """ACF estimate via NUFFT + rectangular (box) smoothing.
+
+    Same parameters and return values as `compute_acf_gaussian_nufft`.
+    The smoothing window size (in samples) is derived from `bin_width` and
+    the average lag spacing; with the common default bin_width=0.5 and a
+    1-day lag spacing, this resolves to a 1-sample window (i.e. no-op),
+    matching the gaussian kernel's "non-overlapping bins" behavior at the
+    same bin_width.
+    """
+    t = np.asarray(t, dtype=float)
+    x = np.asarray(x, dtype=float)
+    lags = np.asarray(lags, dtype=float)
+    lags_eval = np.concatenate(([0.0], lags))
+
+    c_positive = _nufft_power_spectrum_at_lags(t, x, lags_eval, N1, eps)
+
+    dlag = np.mean(np.diff(lags)) if len(lags) > 1 else 1.0
+    window_size = max(1, int(round(2 * bin_width / dlag)))
+    c_smoothed = uniform_filter1d(c_positive, size=window_size, mode="nearest")
+
+    b_eval = compute_b_rectangle(t, lags_eval, bin_width)
+    with np.errstate(divide="ignore", invalid="ignore", over="ignore"):
+        c_eval = c_smoothed / b_eval
+    c = c_eval[1:] / c_eval[0]  # normalize by the (always computed) lag=0 value
+    b = b_eval[1:]
+    return c, b