nn-periodogram 1.0.0__tar.gz

nn_periodogram-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 Niall J. Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nn_periodogram-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: nn-periodogram
+Version: 1.0.0
+Summary: Neural-network false-alarm probabilities and periodograms for astronomical time series
+Author-email: "Niall J. Miller" <niall.j.miller@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2022-2026 Niall J. Miller
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://nialljmiller.com/projects/NN_Periodogram/
+Project-URL: Source, https://github.com/nialljmiller/NN_Periodogram
+Project-URL: Issues, https://github.com/nialljmiller/NN_Periodogram/issues
+Keywords: astronomy,time series,periodogram,variable stars,false alarm probability,neural network
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: torch>=2.0
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == "plot"
+Provides-Extra: convert
+Requires-Dist: h5py; extra == "convert"
+Provides-Extra: astropy
+Requires-Dist: astropy; extra == "astropy"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: h5py; extra == "test"
+Requires-Dist: scikit-learn; extra == "test"
+Requires-Dist: astropy; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: matplotlib; extra == "docs"
+Dynamic: license-file
+
+# NN_Periodogram
+
+**Find the periods of variable stars in any survey's light curves, and tell real periods
+from harmonics and aliases.** A fast periodogram proposes candidate periods; a neural
+network, which sees each light curve folded at P, 2P and P/2 side by side, decides which
+one is real. Runs on a GPU or a CPU, on light curves from ten to hundreds of thousands of
+points.
+
+```python
+import nn_periodogram as nnp
+
+p = nnp.periodogram(time, mag, err)        # find the period
+p.best_period, p.best_fap                  # period and false-alarm probability of the search
+p.peaks                                    # runners-up: [(period, fold FAP), ...]
+p.plot()
+
+nnp.check_period(time, mag, 0.3127, err)   # is a known period right, or really 2P, P/2, an alias?
+nnp.fap(time, mag, [0.6254, 0.3127], err)  # false-alarm probability of given periods
+```
+
+```bash
+pip install nn-periodogram
+```
+
+## How well it works
+
+Held-out stars from five surveys (never used for training or for choosing the model),
+scored against each catalogue's own period: **correct** within 1%, otherwise **harmonic**
+(k/n × the true period, k, n ≤ 4) or wrong. Every method searches the same frequency grid.
+
+| Survey (stars) | **NN_Periodogram** | PDM | Lomb-Scargle |
+|---|---|---|---|
+| OGLE: RR Lyrae, Cepheids, δ Scuti, eclipsing (559) | **92.8%** | 79.1% | 66.0% |
+| Kepler eclipsing binaries (281) | **79.7%** | 47.3% | 5.0% |
+| TESS eclipsing binaries (459) | **78.6%** | 49.2% | 9.4% |
+| VVV: near-infrared, sparse (421; ASAS-SN periods) | **52.5%** | 39.7% | 37.1% |
+| ASAS-SN / VSX, strictly periodic classes (204) | **44.1%** | 36.8% | 29.4% |
+| ASAS-SN / VSX, all classes (585) | **28.9%** | 23.8% | 17.1% |
+
+Lomb-Scargle numbers are identical for astropy, nifty-ls and an exact implementation. Most
+of the gain is in harmonics: Lomb-Scargle reports half the orbital period of an eclipsing
+binary, and phase dispersion often a multiple; NN_Periodogram's harmonic errors are 2–16%
+where theirs are 11–68%. Every difference from PDM is significant (paired McNemar test,
+p < 10⁻³; p = 0.03 for the 204 strictly periodic ASAS-SN stars). ASAS-SN is low for every
+method because many VSX classes (semi-regular, rotational, miscellaneous) have catalogue
+periods that a fold need not confirm, and for a third of its stars no periodogram puts the
+true period among its strongest peaks.
+
+**Robustness** (synthetic light curves with known periods; the same light curves for every
+method):
+
+| Case | NN_Periodogram | Lomb-Scargle | PDM |
+|---|---|---|---|
+| 100 / 300 / 1000 points | **82 / 93 / 99%** | 69 / 71 / 63% | 49 / 67 / 75% |
+| 5% outliers (5–15σ) | **71%** | 43% | 1% |
+| red noise and a trend | **89%** | 65% | 50% |
+| ground-based seasons, nightly sampling | **81%** | 67% | 53% |
+| real OGLE / ASAS-SN / Kepler / TESS / VVV cadences | **85 / 81 / 99 / 77 / 67%** | 65 / 65 / 67 / 53 / 58% | 67 / 57 / 87 / 59 / 31% |
+
+Below about 50 points at signal = noise, no method finds periods reliably.
+
+**False-alarm probability.** `best_fap` is the probability that a light curve with *no*
+periodic signal, of the same size, would produce as good a best fold somewhere in the
+search. It is calibrated on 10,500 searches of pure noise (white, red and outlier-ridden,
+on real cadences from all five surveys), because the best of hundreds of folds always looks
+good by chance. On fresh noise, `best_fap < 0.01` flags 0.2% of light curves and
+`best_fap < 0.1` about 6%. The network's FAP of the best fold alone is `best_fap_fold`.
+
+**Speed** (median per star; same stars and grid; Apple M-series CPU and an RTX 3070 Ti):
+
+| Light curves | NN_Periodogram CPU | NN_Periodogram GPU | PDM (CPU) | exact LS (CPU) | astropy LS | nifty-ls |
+|---|---|---|---|---|---|---|
+| ~400 points (OGLE, ASAS-SN, VVV) | 0.24–0.29 s | ~0.05 s | 0.09–0.11 s | 0.04–0.08 s | 0.05–0.09 s | 0.004 s |
+| ~65,000 points (Kepler, TESS) | 0.36 s | ~0.07 s | 9.9–17.7 s | 7.2–8.5 s | 0.08–0.12 s | 0.007 s |
+
+A Lomb-Scargle periodogram is the first step of NN_Periodogram's search, so it cannot be
+faster than the fastest LS; it costs a fraction of a second per star and does not grow
+with the number of points.
+
+## Ways to use it
+
+* **`periodogram(time, mag, err)`**: standard mode. Fast Lomb-Scargle and 3-harmonic
+  Lomb-Scargle periodograms (Press & Rybicki FFT method, in PyTorch) propose their 40
+  strongest peaks, plus 2×, ½×, 3× and ⅓× each; the network scores them all and the best
+  is refined. `proposers=("ls", "mhls", "pdm")` adds phase-dispersion candidates (slower,
+  about one point more accurate on eclipsing binaries).
+* **`periodogram(..., method="full")`**: the network scores every trial frequency itself.
+* **`check_period(time, mag, period, err)`**: for a period from a catalogue or another
+  method. Compares P with 2P, P/2, 3P, P/3, 3P/2, 2P/3 and the daily and yearly sampling
+  aliases and says which one the network prefers.
+* **`fap(time, mag, period, err)`**: the network's FAP for periods chosen in advance.
+
+Times are days (astropy `Time` and `Quantity` inputs are converted); magnitudes or fluxes;
+errors optional (estimated from point-to-point scatter if absent). Choose the hardware with
+`device="cuda"`, `"mps"` or `"cpu"`; the default is the best available.
+
+## Models
+
+Weights download on first use to `~/.cache/nn_periodogram` (or `$NN_PERIODOGRAM_CACHE`)
+from the GitHub release, with data.nialljmiller.com as a mirror, and are checked against a
+SHA-256.
+
+| name | | size |
+|---|---|---|
+| `periods-v4` (default) | Circular 1-D CNN over multi-resolution binned phase profiles of the folds at P, 2P and P/2, with global light-curve features. | 3 MB |
+| `legacy-2022` | The 2022 NN_FAP network (14 × GRU-1024; Miller et al. 2024), ported exactly from Keras. Exhaustive search only. | 343 MB |
+
+## Training
+
+About 380,000 light curves of known periodic variables, each labelled with the catalogue's
+own period refined by phase dispersion, and each kept only if our own Lomb-Scargle or
+phase-dispersion analysis independently recovers that period (or its double or half):
+OGLE-IV (179,000 RR Lyrae, Cepheids, δ Scuti, eclipsing binaries), ASAS-SN/VSX (96,000),
+VVV/PRIMVS (97,000), Kepler (2,500) and TESS (4,300) eclipsing binaries; 10% of the stars
+of every survey are held out for testing and 10% for validation. Batches mix real stars at
+their period (positives) or at wrong, nearby, harmonic and alias periods (negatives);
+signals injected into quiet VVV stars and into synthetic red, trended and outlier-ridden
+noise on every survey's cadences; magnitude-shuffled light curves; and pure noise. Each
+example is randomly thinned (10 points to all), flipped, time-reversed, cut by a season
+and given rescaled errors. Everything is in `training/`.
+
+## Citing
+
+Please cite the software (Zenodo DOI; see `CITATION.cff`) and
+
+Miller N., Lucas P. W., Sun Y., Guo Z., Cooper W. J., Morris C., 2024, *The verification
+of periodicity with the use of recurrent neural networks*, RAS Techniques and Instruments,
+3, 224. [doi:10.1093/rasti/rzae015](https://doi.org/10.1093/rasti/rzae015)
+
+The pre-2026 code is at the `legacy-2025` tag.

nn_periodogram-1.0.0/README.md

@@ -0,0 +1,130 @@
+# NN_Periodogram
+
+**Find the periods of variable stars in any survey's light curves, and tell real periods
+from harmonics and aliases.** A fast periodogram proposes candidate periods; a neural
+network, which sees each light curve folded at P, 2P and P/2 side by side, decides which
+one is real. Runs on a GPU or a CPU, on light curves from ten to hundreds of thousands of
+points.
+
+```python
+import nn_periodogram as nnp
+
+p = nnp.periodogram(time, mag, err)        # find the period
+p.best_period, p.best_fap                  # period and false-alarm probability of the search
+p.peaks                                    # runners-up: [(period, fold FAP), ...]
+p.plot()
+
+nnp.check_period(time, mag, 0.3127, err)   # is a known period right, or really 2P, P/2, an alias?
+nnp.fap(time, mag, [0.6254, 0.3127], err)  # false-alarm probability of given periods
+```
+
+```bash
+pip install nn-periodogram
+```
+
+## How well it works
+
+Held-out stars from five surveys (never used for training or for choosing the model),
+scored against each catalogue's own period: **correct** within 1%, otherwise **harmonic**
+(k/n × the true period, k, n ≤ 4) or wrong. Every method searches the same frequency grid.
+
+| Survey (stars) | **NN_Periodogram** | PDM | Lomb-Scargle |
+|---|---|---|---|
+| OGLE: RR Lyrae, Cepheids, δ Scuti, eclipsing (559) | **92.8%** | 79.1% | 66.0% |
+| Kepler eclipsing binaries (281) | **79.7%** | 47.3% | 5.0% |
+| TESS eclipsing binaries (459) | **78.6%** | 49.2% | 9.4% |
+| VVV: near-infrared, sparse (421; ASAS-SN periods) | **52.5%** | 39.7% | 37.1% |
+| ASAS-SN / VSX, strictly periodic classes (204) | **44.1%** | 36.8% | 29.4% |
+| ASAS-SN / VSX, all classes (585) | **28.9%** | 23.8% | 17.1% |
+
+Lomb-Scargle numbers are identical for astropy, nifty-ls and an exact implementation. Most
+of the gain is in harmonics: Lomb-Scargle reports half the orbital period of an eclipsing
+binary, and phase dispersion often a multiple; NN_Periodogram's harmonic errors are 2–16%
+where theirs are 11–68%. Every difference from PDM is significant (paired McNemar test,
+p < 10⁻³; p = 0.03 for the 204 strictly periodic ASAS-SN stars). ASAS-SN is low for every
+method because many VSX classes (semi-regular, rotational, miscellaneous) have catalogue
+periods that a fold need not confirm, and for a third of its stars no periodogram puts the
+true period among its strongest peaks.
+
+**Robustness** (synthetic light curves with known periods; the same light curves for every
+method):
+
+| Case | NN_Periodogram | Lomb-Scargle | PDM |
+|---|---|---|---|
+| 100 / 300 / 1000 points | **82 / 93 / 99%** | 69 / 71 / 63% | 49 / 67 / 75% |
+| 5% outliers (5–15σ) | **71%** | 43% | 1% |
+| red noise and a trend | **89%** | 65% | 50% |
+| ground-based seasons, nightly sampling | **81%** | 67% | 53% |
+| real OGLE / ASAS-SN / Kepler / TESS / VVV cadences | **85 / 81 / 99 / 77 / 67%** | 65 / 65 / 67 / 53 / 58% | 67 / 57 / 87 / 59 / 31% |
+
+Below about 50 points at signal = noise, no method finds periods reliably.
+
+**False-alarm probability.** `best_fap` is the probability that a light curve with *no*
+periodic signal, of the same size, would produce as good a best fold somewhere in the
+search. It is calibrated on 10,500 searches of pure noise (white, red and outlier-ridden,
+on real cadences from all five surveys), because the best of hundreds of folds always looks
+good by chance. On fresh noise, `best_fap < 0.01` flags 0.2% of light curves and
+`best_fap < 0.1` about 6%. The network's FAP of the best fold alone is `best_fap_fold`.
+
+**Speed** (median per star; same stars and grid; Apple M-series CPU and an RTX 3070 Ti):
+
+| Light curves | NN_Periodogram CPU | NN_Periodogram GPU | PDM (CPU) | exact LS (CPU) | astropy LS | nifty-ls |
+|---|---|---|---|---|---|---|
+| ~400 points (OGLE, ASAS-SN, VVV) | 0.24–0.29 s | ~0.05 s | 0.09–0.11 s | 0.04–0.08 s | 0.05–0.09 s | 0.004 s |
+| ~65,000 points (Kepler, TESS) | 0.36 s | ~0.07 s | 9.9–17.7 s | 7.2–8.5 s | 0.08–0.12 s | 0.007 s |
+
+A Lomb-Scargle periodogram is the first step of NN_Periodogram's search, so it cannot be
+faster than the fastest LS; it costs a fraction of a second per star and does not grow
+with the number of points.
+
+## Ways to use it
+
+* **`periodogram(time, mag, err)`**: standard mode. Fast Lomb-Scargle and 3-harmonic
+  Lomb-Scargle periodograms (Press & Rybicki FFT method, in PyTorch) propose their 40
+  strongest peaks, plus 2×, ½×, 3× and ⅓× each; the network scores them all and the best
+  is refined. `proposers=("ls", "mhls", "pdm")` adds phase-dispersion candidates (slower,
+  about one point more accurate on eclipsing binaries).
+* **`periodogram(..., method="full")`**: the network scores every trial frequency itself.
+* **`check_period(time, mag, period, err)`**: for a period from a catalogue or another
+  method. Compares P with 2P, P/2, 3P, P/3, 3P/2, 2P/3 and the daily and yearly sampling
+  aliases and says which one the network prefers.
+* **`fap(time, mag, period, err)`**: the network's FAP for periods chosen in advance.
+
+Times are days (astropy `Time` and `Quantity` inputs are converted); magnitudes or fluxes;
+errors optional (estimated from point-to-point scatter if absent). Choose the hardware with
+`device="cuda"`, `"mps"` or `"cpu"`; the default is the best available.
+
+## Models
+
+Weights download on first use to `~/.cache/nn_periodogram` (or `$NN_PERIODOGRAM_CACHE`)
+from the GitHub release, with data.nialljmiller.com as a mirror, and are checked against a
+SHA-256.
+
+| name | | size |
+|---|---|---|
+| `periods-v4` (default) | Circular 1-D CNN over multi-resolution binned phase profiles of the folds at P, 2P and P/2, with global light-curve features. | 3 MB |
+| `legacy-2022` | The 2022 NN_FAP network (14 × GRU-1024; Miller et al. 2024), ported exactly from Keras. Exhaustive search only. | 343 MB |
+
+## Training
+
+About 380,000 light curves of known periodic variables, each labelled with the catalogue's
+own period refined by phase dispersion, and each kept only if our own Lomb-Scargle or
+phase-dispersion analysis independently recovers that period (or its double or half):
+OGLE-IV (179,000 RR Lyrae, Cepheids, δ Scuti, eclipsing binaries), ASAS-SN/VSX (96,000),
+VVV/PRIMVS (97,000), Kepler (2,500) and TESS (4,300) eclipsing binaries; 10% of the stars
+of every survey are held out for testing and 10% for validation. Batches mix real stars at
+their period (positives) or at wrong, nearby, harmonic and alias periods (negatives);
+signals injected into quiet VVV stars and into synthetic red, trended and outlier-ridden
+noise on every survey's cadences; magnitude-shuffled light curves; and pure noise. Each
+example is randomly thinned (10 points to all), flipped, time-reversed, cut by a season
+and given rescaled errors. Everything is in `training/`.
+
+## Citing
+
+Please cite the software (Zenodo DOI; see `CITATION.cff`) and
+
+Miller N., Lucas P. W., Sun Y., Guo Z., Cooper W. J., Morris C., 2024, *The verification
+of periodicity with the use of recurrent neural networks*, RAS Techniques and Instruments,
+3, 224. [doi:10.1093/rasti/rzae015](https://doi.org/10.1093/rasti/rzae015)
+
+The pre-2026 code is at the `legacy-2025` tag.

nn_periodogram-1.0.0/nn_periodogram/__init__.py

@@ -0,0 +1,13 @@
+"""NN_Periodogram: neural-network false-alarm probabilities and periodograms for time series.
+
+    import nn_periodogram
+    p = nn_periodogram.periodogram(time, mag)        # search
+    p.best_period, p.best_fap, p.peaks
+    nn_periodogram.fap(time, mag, 0.5077)           # score given period(s)
+    nn_periodogram.check_period(time, mag, 1.0155)  # is it P, 2P, P/2 or an alias?
+"""
+
+from .periodogram import PeriodCheck, Periodogram, check_period, fap, periodogram
+
+__version__ = "1.0.0"
+__all__ = ["fap", "periodogram", "check_period", "Periodogram", "PeriodCheck", "__version__"]

nn_periodogram-1.0.0/nn_periodogram/classical.py

@@ -0,0 +1,171 @@
+"""Fast classical periodograms on the GPU: generalised Lomb-Scargle and phase dispersion.
+
+Used by periodogram(method="hybrid") to propose candidate periods cheaply, and
+by the training data verification. Phases are computed in float64 (time x
+frequency over long baselines needs it), the rest in float32.
+"""
+
+import numpy as np
+import torch
+
+from .features import phase_device
+
+
+def gls(t, y, dy, freqs, device, chunk=None):
+    """Generalised Lomb-Scargle power (standard normalisation, floating mean)."""
+    w = 1.0 / dy ** 2
+    w = w / w.sum()
+    y = y - (w * y).sum()
+    pdev = phase_device(device)
+    tt = torch.tensor(t - t.min(), dtype=torch.float64, device=pdev)
+    wt = torch.tensor(w, dtype=torch.float32, device=device)
+    yt = torch.tensor(y, dtype=torch.float32, device=device)
+    yy = float((w * y * y).sum())
+    chunk = chunk or max(1, 2 ** 23 // len(t))          # ~2^23 phases per pass: bounded memory at any length
+    out = []
+    for s in range(0, len(freqs), chunk):
+        f = torch.tensor(freqs[s:s + chunk], dtype=torch.float64, device=pdev)
+        ph = torch.remainder(f[:, None] * tt[None, :], 1.0).float().to(device) * (2 * np.pi)
+        c, sn = torch.cos(ph), torch.sin(ph)
+        C, S = c @ wt, sn @ wt
+        YC, YS = c @ (wt * yt), sn @ (wt * yt)
+        CC = (c * c) @ wt - C * C
+        SS = 1.0 - (c * c) @ wt - S * S
+        CS = (c * sn) @ wt - C * S
+        D = CC * SS - CS * CS
+        out.append(((SS * YC ** 2 + CC * YS ** 2 - 2 * CS * YC * YS) / (yy * D)).cpu().numpy())
+    return np.concatenate(out)
+
+
+def pdm_theta(t, y, freqs, device, bins=(16, 32)):
+    """Phase dispersion at each frequency: within-bin variance / total variance (lower = tighter fold)."""
+    pdev = phase_device(device)
+    tt = torch.tensor(t - t.min(), dtype=torch.float64, device=pdev)
+    yt = torch.tensor(y - y.mean(), dtype=torch.float32, device=device)
+    total = float((yt ** 2).mean())
+    best = None
+    step = max(1, 2 ** 23 // len(t))                   # bounded memory at any length
+    for s in range(0, len(freqs), step):
+        f = torch.tensor(freqs[s:s + step], dtype=torch.float64, device=pdev)
+        ph = torch.remainder(f[:, None] * tt[None, :], 1.0).float().to(device)
+        thetas = []
+        for nb in bins:
+            idx = torch.clamp((ph * nb).long(), 0, nb - 1)
+            n = torch.zeros(len(f), nb, device=device).scatter_add_(1, idx, torch.ones_like(ph))
+            s1 = torch.zeros_like(n).scatter_add_(1, idx, yt.expand_as(ph))
+            s2 = torch.zeros_like(n).scatter_add_(1, idx, (yt ** 2).expand_as(ph))
+            within = (s2 - s1 ** 2 / n.clamp_min(1)).sum(1) / len(t)
+            thetas.append(within / total)
+        th = torch.minimum(*thetas).cpu().numpy()
+        best = th if best is None else np.concatenate([best, th])
+    return best
+
+
+
+
+# ---------------------------------------------------------------------------
+# Fast Lomb-Scargle (Press & Rybicki 1989): O(N + M log M) instead of O(N M)
+# ---------------------------------------------------------------------------
+
+def _extirpolate(x, h, n, order=8):
+    """Spread values h at real grid positions x (0 <= x < n) onto n integer nodes so that
+    sums of any smooth n-periodic function over the nodes reproduce sums over the points
+    (Lagrange weights over `order` neighbouring nodes, wrapping around the grid)."""
+    real = x.dtype
+    base = torch.floor(x).long() - (order // 2 - 1)
+    nodes = base[:, None] + torch.arange(order, device=x.device)
+    dx = x[:, None] - nodes.to(real)                     # (N, order)
+    out = torch.zeros(n, dtype=h.dtype, device=h.device)
+    for i in range(order):
+        w = torch.ones_like(x)
+        for j in range(order):
+            if j != i:
+                w = w * dx[:, j] / (i - j)
+        out.index_add_(0, torch.remainder(nodes[:, i], n), h * w.to(h.dtype))
+    return out
+
+
+def _trig_sums(t, h, f0, df, nf, oversample=4):
+    """sum_j h_j exp(2 pi i f t_j) for f = f0 + k df, k = 0..nf-1, via one FFT.
+    t must start at 0 and be in the working precision (float64 on CPU)."""
+    real = t.dtype
+    cplx = torch.complex128 if real == torch.float64 else torch.complex64
+    nfft = 1 << int(np.ceil(np.log2(oversample * nf)))
+    hc = h.to(cplx) * torch.exp(2j * np.pi * torch.remainder(f0 * t, 1.0)).to(cplx)   # shift to f0
+    x = torch.remainder(df * t * nfft, nfft)
+    grid = _extirpolate(x, hc, nfft)
+    return torch.fft.ifft(grid)[:nf] * nfft
+
+
+def gls_fast(t, y, dy, f0, df, nf, device=None):
+    """Generalised Lomb-Scargle power on the regular grid f0 + k df (k < nf), same
+    normalisation as gls(), via Press & Rybicki extirpolation and FFTs.
+
+    Runs in float64 on the CPU and float32 on GPUs; precise enough for finding peaks
+    (use gls() to evaluate a few exact values)."""
+    device = torch.device(device or "cpu")
+    real = torch.float64 if device.type == "cpu" else torch.float32
+    if device.type == "mps":                 # no float64 / limited complex support on MPS
+        device, real = torch.device("cpu"), torch.float64
+    t = np.asarray(t, float); y = np.asarray(y, float); dy = np.asarray(dy, float)
+    w = 1.0 / dy ** 2
+    w = w / w.sum()
+    y = y - (w * y).sum()
+    yy = float((w * y * y).sum())
+    tt = torch.tensor(t - t.min(), dtype=torch.float64, device=device).to(real)
+    wt = torch.tensor(w, dtype=real, device=device)
+    yt = torch.tensor(y, dtype=real, device=device)
+    A = _trig_sums(tt, wt, f0, df, nf)                    # sum w e^{iwt}
+    B = _trig_sums(tt, wt * yt, f0, df, nf)               # sum w y e^{iwt}
+    A2 = _trig_sums(tt, wt, 2 * f0, 2 * df, nf)           # sum w e^{2iwt}
+    C, S = A.real, A.imag
+    YC, YS = B.real, B.imag
+    CC = 0.5 * (1 + A2.real) - C * C
+    SS = 0.5 * (1 - A2.real) - S * S
+    CS = 0.5 * A2.imag - C * S
+    D = CC * SS - CS * CS
+    p = (SS * YC ** 2 + CC * YS ** 2 - 2 * CS * YC * YS) / (yy * D)
+    return p.cpu().numpy().astype(np.float64)
+
+
+def mhls_fast(t, y, dy, f0, df, nf, nterms=2, device=None):
+    """Multi-harmonic (Fourier series, `nterms` harmonics, floating mean) Lomb-Scargle power
+    on the grid f0 + k df: the fraction of weighted variance explained at each frequency.
+    Non-sinusoidal signals (eclipsing binaries, RR Lyrae) peak at their true period rather
+    than a harmonic. O(N + M log M) via the same FFT trig sums as gls_fast (Palmer 2009);
+    nterms=1 is the generalised Lomb-Scargle."""
+    device = torch.device(device or "cpu")
+    real = torch.float64 if device.type == "cpu" else torch.float32
+    if device.type == "mps":
+        device, real = torch.device("cpu"), torch.float64
+    t = np.asarray(t, float); y = np.asarray(y, float); dy = np.asarray(dy, float)
+    w = 1.0 / dy ** 2
+    w = w / w.sum()
+    y = y - (w * y).sum()
+    yy = float((w * y * y).sum())
+    tt = torch.tensor(t - t.min(), dtype=torch.float64, device=device).to(real)
+    wt = torch.tensor(w, dtype=real, device=device)
+    yt = torch.tensor(y, dtype=real, device=device)
+    K = nterms
+    A = [torch.ones(nf, dtype=tt.dtype, device=device).to(torch.complex128 if real == torch.float64 else torch.complex64)]
+    A += [_trig_sums(tt, wt, m * f0, m * df, nf) for m in range(1, 2 * K + 1)]   # sum w e^{i m w t}
+    B = [_trig_sums(tt, wt * yt, k * f0, k * df, nf) for k in range(1, K + 1)]   # sum w y e^{i k w t}
+    Cm = lambda m: A[abs(m)].real                                               # noqa: E731
+    Sm = lambda m: torch.sign(torch.tensor(float(m))) * A[abs(m)].imag if m else torch.zeros_like(A[0].real)  # noqa: E731
+    n = 2 * K + 1
+    M = torch.empty(nf, n, n, dtype=real, device=device)
+    rhs = torch.zeros(nf, n, dtype=real, device=device)
+    M[:, 0, 0] = 1.0
+    for k in range(1, K + 1):
+        ck, sk = 2 * k - 1, 2 * k
+        M[:, 0, ck] = M[:, ck, 0] = Cm(k)
+        M[:, 0, sk] = M[:, sk, 0] = Sm(k)
+        rhs[:, ck], rhs[:, sk] = B[k - 1].real, B[k - 1].imag
+        for l in range(1, K + 1):
+            cl, sl = 2 * l - 1, 2 * l
+            M[:, ck, cl] = 0.5 * (Cm(k - l) + Cm(k + l))
+            M[:, sk, sl] = 0.5 * (Cm(k - l) - Cm(k + l))
+            M[:, ck, sl] = M[:, sl, ck] = 0.5 * (Sm(k + l) - Sm(k - l))
+    M = M + 1e-10 * torch.eye(n, dtype=real, device=device)
+    sol = torch.linalg.solve(M, rhs[..., None])[..., 0]
+    return ((rhs * sol).sum(1) / yy).cpu().numpy().astype(np.float64)