toeplitz-ls 1.0.0rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. toeplitz_ls-1.0.0rc1/LICENSE +21 -0
  2. toeplitz_ls-1.0.0rc1/PKG-INFO +269 -0
  3. toeplitz_ls-1.0.0rc1/README.md +244 -0
  4. toeplitz_ls-1.0.0rc1/include/linalg.h +96 -0
  5. toeplitz_ls-1.0.0rc1/include/nanofft.h +483 -0
  6. toeplitz_ls-1.0.0rc1/include/nanofft_exp_coeffs.h +42 -0
  7. toeplitz_ls-1.0.0rc1/include/nanofft_precision.h +147 -0
  8. toeplitz_ls-1.0.0rc1/include/nanofft_vecmath.h +144 -0
  9. toeplitz_ls-1.0.0rc1/include/nufft1.h +63 -0
  10. toeplitz_ls-1.0.0rc1/include/scaling_generic.h +23 -0
  11. toeplitz_ls-1.0.0rc1/include/tls.h +85 -0
  12. toeplitz_ls-1.0.0rc1/include/tls_cpu.h +69 -0
  13. toeplitz_ls-1.0.0rc1/include/tls_export.h +39 -0
  14. toeplitz_ls-1.0.0rc1/include/tls_internal.h +51 -0
  15. toeplitz_ls-1.0.0rc1/include/tls_platform.h +165 -0
  16. toeplitz_ls-1.0.0rc1/include/tls_tuning.h +73 -0
  17. toeplitz_ls-1.0.0rc1/include/utils.h +40 -0
  18. toeplitz_ls-1.0.0rc1/pyproject.toml +17 -0
  19. toeplitz_ls-1.0.0rc1/src/chi2per.c +2219 -0
  20. toeplitz_ls-1.0.0rc1/src/cpu_features.c +196 -0
  21. toeplitz_ls-1.0.0rc1/src/linalg.c +685 -0
  22. toeplitz_ls-1.0.0rc1/src/nanofft.c +1036 -0
  23. toeplitz_ls-1.0.0rc1/src/nufft1.c +1250 -0
  24. toeplitz_ls-1.0.0rc1/src/probe_arm64.c +36 -0
  25. toeplitz_ls-1.0.0rc1/src/tuning.c +55 -0
  26. toeplitz_ls-1.0.0rc1/src/utils.c +273 -0
  27. toeplitz_ls-1.0.0rc1/tls_source_build.py +231 -0
  28. toeplitz_ls-1.0.0rc1/toeplitz_ls/__init__.py +26 -0
  29. toeplitz_ls-1.0.0rc1/toeplitz_ls/_dispatch.py +379 -0
  30. toeplitz_ls-1.0.0rc1/toeplitz_ls/_fastchi2.py +705 -0
  31. toeplitz_ls-1.0.0rc1/toeplitz_ls/_ihs.py +322 -0
  32. toeplitz_ls-1.0.0rc1/toeplitz_ls/utils.py +705 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kacper Rutkowski
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,269 @@
1
+ Metadata-Version: 2.1
2
+ Name: toeplitz-ls
3
+ Version: 1.0.0rc1
4
+ Summary: The reference implementation of the Toeplitz formulation of the multiharmonic least-squares periodogram (AoVMH / FastChi2).
5
+ License: MIT
6
+ Author: Kacper Rutkowski
7
+ Keywords: astronomy,periodogram,least squares,Toeplitz,FFT,time series
8
+ Requires-Python: >=3.8
9
+ Classifier: Development Status :: 5 - Production/Stable
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: MacOS
13
+ Classifier: Operating System :: Microsoft :: Windows
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: C
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
18
+ Project-URL: Homepage, https://github.com/kkrutkowski/Toeplitz-LS
19
+ Project-URL: Source, https://github.com/kkrutkowski/Toeplitz-LS
20
+ Project-URL: Issues, https://github.com/kkrutkowski/Toeplitz-LS/issues
21
+ Requires-Dist: numpy>=1.17.3
22
+ Provides-Extra: tlsdd
23
+ Requires-Dist: mpmath>=1.0; extra == "tlsdd"
24
+ Description-Content-Type: text/markdown
25
+
26
+ # Toeplitz-LS
27
+
28
+ Reference implementation of the multiharmonic least-squares periodogram
29
+ (AoVMH(W) / FastChi²) using a blocked NuFFT and a fast Toeplitz solver.
30
+
31
+ ## Installation
32
+
33
+ The package requires Python >= 3.8 and NumPy >= 1.17.3; the optional `tlsdd`
34
+ extra requires mpmath >= 1.0. Prebuilt wheels include runtime microarchitecture
35
+ dispatch, so installing from PyPI is the recommended path:
36
+
37
+ ```console
38
+ pip install Toeplitz-LS
39
+ # or with mpmath for the double-double wrappers:
40
+ pip install "Toeplitz-LS[tlsdd]"
41
+ ```
42
+
43
+ To build from source instead:
44
+
45
+ ```console
46
+ git clone https://github.com/kkrutkowski/Toeplitz-LS.git --depth=1
47
+ cd ./Toeplitz-LS
48
+ make native # or 'make generic' for a portable baseline
49
+ cd ./toeplitz-ls
50
+ pip3 install . # use 'pip3 install ".[tlsdd]"' for the mpmath wrappers
51
+ ```
52
+
53
+ `make native` may be slightly faster thanks to custom-generated scaling
54
+ constants and host tuning, though because release wheels ship multiple
55
+ microarchitecture builds via runtime dispatch, that difference is generally
56
+ insignificant.
57
+
58
+ ## Supported platforms
59
+
60
+ Linux, Windows, and macOS are supported on x86-64 and ARM64.
61
+
62
+ ## Runtime dispatch
63
+
64
+ Release builds bundle more than one native library. At import,
65
+ `toeplitz_ls` probes the CPU and loads the widest variant it can execute,
66
+ falling back to the baseline library; the choice is made once, so a
67
+ periodogram call pays nothing for it. `TOEPLITZ_LS_DISPATCH` forces a specific
68
+ variant, and `TOEPLITZ_LS_DISPATCH=list` prints the available variants.
69
+
70
+ ## Usage
71
+
72
+ The package exposes two periodogram families. The FastChi2/AoVMH modules
73
+ (`tlsf`, `tls`, `tlsdd`) use the Toeplitz least-squares solve. The IHS modules
74
+ (`ihsf`, `ihs`, `ihsdd`) use the incoherent harmonic sum: one NuFFT per
75
+ harmonic, no linear solve, and only the `raw`, `nll`, or `default`
76
+ statistic. Each
77
+ family has single-, double-, and double-double-precision variants. The single-
78
+ and double-precision variants accept and return NumPy arrays. The double-double
79
+ variants rely on compensated arithmetic and operate on a 106-bit mantissa; they
80
+ use mpmath's `mpf` type to bridge the gap between the library's internal
81
+ representation and Python's native numeric types. The `get_peaks` helper turns
82
+ a periodogram into a sorted, interpolated peak list for printing or saving.
83
+
84
+ ## Normalizations
85
+
86
+ For the FastChi2 modules (`tlsf`, `tls`, `tlsdd`), `power()` and `autopower()`
87
+ accept `normalization=`:
88
+
89
+ | value | output | notes |
90
+ |---|---|---|
91
+ | `"standard"` (default) | coefficient of determination `R^2` | |
92
+ | `"anova"` | ANOVA / `F` statistic | Schwarzenberg-Czerny's ANOVA convention |
93
+ | `"nll"` | natural negative log false-alarm probability | `-ln(FAP)` |
94
+
95
+ For `nterms = d` harmonics:
96
+
97
+ - `"standard"` is the coefficient of determination `R^2` of the full model.
98
+ Values at or above 1 are numerical artefacts of an ill-conditioned solve and
99
+ are reported as 0.
100
+ - `"anova"` is the ANOVA `F` statistic in Schwarzenberg-Czerny's convention.
101
+ - `"nll"` is the natural-log negative false-alarm probability, `-ln(FAP)`,
102
+ computed from the direct Pochhammer/incomplete-beta statistic with its
103
+ finite-sample correction. `Neff = (sum w)^2 / sum(w^2)` with `w = 1/dy^2`.
104
+
105
+ The `cond` array returned when `autonan=False` is the Toeplitz condition upper
106
+ bound `(2*nterms + 1) * P`, where `P` is the Cybenko reflection-coefficient
107
+ product.
108
+
109
+ ## IHS periodogram
110
+
111
+ The `ihsf`, `ihs`, and `ihsdd` modules expose the same `power()` and
112
+ `autopower()` call shape, but no `solver`, no `autonan`, and no condition
113
+ array:
114
+
115
+ ```python
116
+ from toeplitz_ls import ihs
117
+
118
+ frequency, power = ihs.autopower(t, y, dy=None, nterms=3, normalization="nll")
119
+ ```
120
+
121
+ IHS is a simplified formulation of a similar periodogram. It assumes that the
122
+ harmonic frequencies are independent (a regression from the standard
123
+ least-squares periodogram) but not orthogonal. It evaluates `d` NuFFTs instead
124
+ of `3d` and replaces the `O(d^2)` normal-equation solve with an `O(d)` power
125
+ accumulation, so it is at least 3x less computationally expensive. In practice
126
+ it is usually slightly less accurate than FastChi2.
127
+
128
+ The three statistics are:
129
+
130
+ - `"raw"`: a direct display statistic built from the normalized per-harmonic
131
+ Rayleigh powers. It is not a calibrated false-alarm probability, and for
132
+ `nterms > 1` it is not a bounded `R^2`; it may exceed 1.
133
+ - `"nll"`: the negative log false-alarm probability. Each harmonic's Rayleigh
134
+ power is passed through Wilkie's (1983) finite-sample correction, and the
135
+ harmonic sum is then passed through the Erlang correction.
136
+ `Neff = (sum |wy|)^2 / sum(wy^2)`, where `wy = w * (y - ymean)`. Use this
137
+ statistic when a reliable significance estimate is needed.
138
+ - `"default"` (the default): the same initial formula and Erlang correction as
139
+ `"nll"`, but without the finite-sample Wilkie correction. This still produces
140
+ NLL estimates, just less accurately.
141
+
142
+ IHS is not suitable when `nterms^4 > Neff`, where `Neff` is the raw-weight
143
+ effective sample size from the FastChi2/TLS path; the Python wrappers emit a
144
+ `RuntimeWarning` in that case. Use the FastChi2 modules or reduce `nterms`.
145
+
146
+ ## Free-threaded (GIL-free) Python support
147
+
148
+ The library is written almost exclusively in C and called through `ctypes`, so
149
+ independent `power()`/`autopower()` calls release the GIL and can run in
150
+ parallel from a `ThreadPoolExecutor`. Multithreading is therefore expected to
151
+ give major performance gains even on regular CPython; for optimum performance,
152
+ use a free-threaded build (PEP 703, optional since Python 3.13).
153
+
154
+ mpmath is not thread-safe by default. When using `tlsdd` in a multithreaded
155
+ context, each worker should keep its own `mp` context via `mpmath.workprec()`
156
+ rather than mutating the global `mp.prec`.
157
+
158
+ ## NaN handling
159
+
160
+ When the system matrix at a given frequency is numerically unstable, the solver
161
+ returns NaN rather than raising an exception. Use `np.nanargmax()` and
162
+ `np.nanmax()` in place of their standard counterparts to safely recover the
163
+ peak frequency and power without short-circuiting on degenerate bins.
164
+
165
+ For manual filtering, call `power()` or `autopower()` with `autonan=False` to
166
+ receive rough conditionality estimates alongside the periodogram. These
167
+ estimates are solver-specific: LDLT reports a diagonal-ratio estimate, while
168
+ the three Toeplitz solvers (`levinson`, `zohar`, and `bareiss`) return a
169
+ reflection-coefficient-based upper bound `(2*nterms + 1) * P`. The Toeplitz
170
+ estimates are generally much higher (and more reliable) for the same
171
+ frequencies, so threshold values should be chosen with the solver family in
172
+ mind.
173
+
174
+ ### Example usage of `tls` and `tlsf`
175
+
176
+ ```python
177
+ import numpy as np
178
+ import matplotlib.pyplot as plt
179
+ from toeplitz_ls import tls
180
+
181
+ rng = np.random.default_rng(seed=123)
182
+ N = 1000
183
+ t = np.sort(rng.uniform(0, 1000, size=N))
184
+ y = np.sin(50 * t) + 0.5 * np.sin(150 * t) + 1 + rng.poisson(size=N)
185
+
186
+ # Compute the generalized Scargle periodogram.
187
+ freq, r2 = tls.autopower(
188
+ t, y, dy=None,
189
+ fmax=12, # default value
190
+ nterms=1, # generalized Scargle periodogram
191
+ oversampling=5, # frequency density, relative to a dense, uniform FFT
192
+ backend="pswf43", # or "pswf21", "lra"
193
+ normalization="standard", # or "anova", "nll"
194
+ )
195
+
196
+ best_idx = np.nanargmax(r2)
197
+ best_freq = freq[best_idx]
198
+ best_power = r2[best_idx]
199
+
200
+ print(f"Peak frequency: {best_freq:.6g} (R^2 = {best_power:.6g})")
201
+
202
+ plt.figure(figsize=(12, 5))
203
+ plt.plot(freq, r2, label="degree = 1", color="red")
204
+ plt.axvline(best_freq, linestyle="--", color="black", alpha=0.7)
205
+ plt.xlabel("Frequency")
206
+ plt.ylabel("Coefficient of determination")
207
+ plt.legend()
208
+ plt.tight_layout()
209
+ plt.show()
210
+ ```
211
+
212
+ ### Example usage with an OGLE-BLAP light curve
213
+
214
+ ```python
215
+ from pathlib import Path
216
+ from tempfile import TemporaryDirectory
217
+ from urllib.request import urlretrieve
218
+
219
+ import numpy as np
220
+ from toeplitz_ls import tlsf, get_peaks
221
+
222
+ url = "https://www.astrouw.edu.pl/ogle/ogle4/OCVS/BLAP/phot/phot_ogle4/I/OGLE-BLAP-035.dat"
223
+
224
+ with TemporaryDirectory() as tmpdir:
225
+ data_path = Path(tmpdir) / "OGLE-BLAP-035.dat"
226
+ urlretrieve(url, str(data_path))
227
+ t, y, _dy = np.loadtxt(data_path, unpack=True)
228
+
229
+ t = t - t.min()
230
+
231
+ # BLAPs require high-frequency search. Ignore the photometric error estimates here.
232
+ freq, power, cond = tlsf.autopower(
233
+ t, y, dy=None,
234
+ fmax=100,
235
+ nterms=3,
236
+ oversampling=5,
237
+ solver="levinson", # or 'zohar', 'bareiss', 'ldlt', 'svd'
238
+ normalization="anova",
239
+ autonan=False,
240
+ )
241
+
242
+ peaks = get_peaks(freq, power, cond, threshold=10)
243
+ peaks.print(10)
244
+ ```
245
+
246
+ ## Development
247
+
248
+ The C and Python halves share one style: `.clang-format` and `ruff.toml` use the
249
+ same 160-column budget and 4-space indentation, so `make format` leaves both in
250
+ a state `make format-check` accepts.
251
+
252
+ ```console
253
+ make format # clang-format (src, include, tests) + ruff format/check (package, dispatch)
254
+ make format-check # the same, without writing
255
+ make generic # portable build for this machine's architecture
256
+ make native # build for this machine
257
+ make -C tests check
258
+ ```
259
+
260
+ Build artifacts (objects, staged wheel payloads, `.toolchains/`) live under
261
+ `.build/`. Nothing is committed to it.
262
+
263
+ ## Performance
264
+
265
+ The hot path is a blocked NuFFT sweep with vectorized transforms, deferred
266
+ permutations, and block-sized work arrays. On a modern
267
+ x86-64 CPU, a periodogram over roughly 10^4 frequencies takes on the order of
268
+ milliseconds; the IHS path is at least 3x cheaper. The benchmark harness lives
269
+ in `tests/`.
@@ -0,0 +1,244 @@
1
+ # Toeplitz-LS
2
+
3
+ Reference implementation of the multiharmonic least-squares periodogram
4
+ (AoVMH(W) / FastChi²) using a blocked NuFFT and a fast Toeplitz solver.
5
+
6
+ ## Installation
7
+
8
+ The package requires Python >= 3.8 and NumPy >= 1.17.3; the optional `tlsdd`
9
+ extra requires mpmath >= 1.0. Prebuilt wheels include runtime microarchitecture
10
+ dispatch, so installing from PyPI is the recommended path:
11
+
12
+ ```console
13
+ pip install Toeplitz-LS
14
+ # or with mpmath for the double-double wrappers:
15
+ pip install "Toeplitz-LS[tlsdd]"
16
+ ```
17
+
18
+ To build from source instead:
19
+
20
+ ```console
21
+ git clone https://github.com/kkrutkowski/Toeplitz-LS.git --depth=1
22
+ cd ./Toeplitz-LS
23
+ make native # or 'make generic' for a portable baseline
24
+ cd ./toeplitz-ls
25
+ pip3 install . # use 'pip3 install ".[tlsdd]"' for the mpmath wrappers
26
+ ```
27
+
28
+ `make native` may be slightly faster thanks to custom-generated scaling
29
+ constants and host tuning, though because release wheels ship multiple
30
+ microarchitecture builds via runtime dispatch, that difference is generally
31
+ insignificant.
32
+
33
+ ## Supported platforms
34
+
35
+ Linux, Windows, and macOS are supported on x86-64 and ARM64.
36
+
37
+ ## Runtime dispatch
38
+
39
+ Release builds bundle more than one native library. At import,
40
+ `toeplitz_ls` probes the CPU and loads the widest variant it can execute,
41
+ falling back to the baseline library; the choice is made once, so a
42
+ periodogram call pays nothing for it. `TOEPLITZ_LS_DISPATCH` forces a specific
43
+ variant, and `TOEPLITZ_LS_DISPATCH=list` prints the available variants.
44
+
45
+ ## Usage
46
+
47
+ The package exposes two periodogram families. The FastChi2/AoVMH modules
48
+ (`tlsf`, `tls`, `tlsdd`) use the Toeplitz least-squares solve. The IHS modules
49
+ (`ihsf`, `ihs`, `ihsdd`) use the incoherent harmonic sum: one NuFFT per
50
+ harmonic, no linear solve, and only the `raw`, `nll`, or `default`
51
+ statistic. Each
52
+ family has single-, double-, and double-double-precision variants. The single-
53
+ and double-precision variants accept and return NumPy arrays. The double-double
54
+ variants rely on compensated arithmetic and operate on a 106-bit mantissa; they
55
+ use mpmath's `mpf` type to bridge the gap between the library's internal
56
+ representation and Python's native numeric types. The `get_peaks` helper turns
57
+ a periodogram into a sorted, interpolated peak list for printing or saving.
58
+
59
+ ## Normalizations
60
+
61
+ For the FastChi2 modules (`tlsf`, `tls`, `tlsdd`), `power()` and `autopower()`
62
+ accept `normalization=`:
63
+
64
+ | value | output | notes |
65
+ |---|---|---|
66
+ | `"standard"` (default) | coefficient of determination `R^2` | |
67
+ | `"anova"` | ANOVA / `F` statistic | Schwarzenberg-Czerny's ANOVA convention |
68
+ | `"nll"` | natural negative log false-alarm probability | `-ln(FAP)` |
69
+
70
+ For `nterms = d` harmonics:
71
+
72
+ - `"standard"` is the coefficient of determination `R^2` of the full model.
73
+ Values at or above 1 are numerical artefacts of an ill-conditioned solve and
74
+ are reported as 0.
75
+ - `"anova"` is the ANOVA `F` statistic in Schwarzenberg-Czerny's convention.
76
+ - `"nll"` is the natural-log negative false-alarm probability, `-ln(FAP)`,
77
+ computed from the direct Pochhammer/incomplete-beta statistic with its
78
+ finite-sample correction. `Neff = (sum w)^2 / sum(w^2)` with `w = 1/dy^2`.
79
+
80
+ The `cond` array returned when `autonan=False` is the Toeplitz condition upper
81
+ bound `(2*nterms + 1) * P`, where `P` is the Cybenko reflection-coefficient
82
+ product.
83
+
84
+ ## IHS periodogram
85
+
86
+ The `ihsf`, `ihs`, and `ihsdd` modules expose the same `power()` and
87
+ `autopower()` call shape, but no `solver`, no `autonan`, and no condition
88
+ array:
89
+
90
+ ```python
91
+ from toeplitz_ls import ihs
92
+
93
+ frequency, power = ihs.autopower(t, y, dy=None, nterms=3, normalization="nll")
94
+ ```
95
+
96
+ IHS is a simplified formulation of a similar periodogram. It assumes that the
97
+ harmonic frequencies are independent (a regression from the standard
98
+ least-squares periodogram) but not orthogonal. It evaluates `d` NuFFTs instead
99
+ of `3d` and replaces the `O(d^2)` normal-equation solve with an `O(d)` power
100
+ accumulation, so it is at least 3x less computationally expensive. In practice
101
+ it is usually slightly less accurate than FastChi2.
102
+
103
+ The three statistics are:
104
+
105
+ - `"raw"`: a direct display statistic built from the normalized per-harmonic
106
+ Rayleigh powers. It is not a calibrated false-alarm probability, and for
107
+ `nterms > 1` it is not a bounded `R^2`; it may exceed 1.
108
+ - `"nll"`: the negative log false-alarm probability. Each harmonic's Rayleigh
109
+ power is passed through Wilkie's (1983) finite-sample correction, and the
110
+ harmonic sum is then passed through the Erlang correction.
111
+ `Neff = (sum |wy|)^2 / sum(wy^2)`, where `wy = w * (y - ymean)`. Use this
112
+ statistic when a reliable significance estimate is needed.
113
+ - `"default"` (the default): the same initial formula and Erlang correction as
114
+ `"nll"`, but without the finite-sample Wilkie correction. This still produces
115
+ NLL estimates, just less accurately.
116
+
117
+ IHS is not suitable when `nterms^4 > Neff`, where `Neff` is the raw-weight
118
+ effective sample size from the FastChi2/TLS path; the Python wrappers emit a
119
+ `RuntimeWarning` in that case. Use the FastChi2 modules or reduce `nterms`.
120
+
121
+ ## Free-threaded (GIL-free) Python support
122
+
123
+ The library is written almost exclusively in C and called through `ctypes`, so
124
+ independent `power()`/`autopower()` calls release the GIL and can run in
125
+ parallel from a `ThreadPoolExecutor`. Multithreading is therefore expected to
126
+ give major performance gains even on regular CPython; for optimum performance,
127
+ use a free-threaded build (PEP 703, optional since Python 3.13).
128
+
129
+ mpmath is not thread-safe by default. When using `tlsdd` in a multithreaded
130
+ context, each worker should keep its own `mp` context via `mpmath.workprec()`
131
+ rather than mutating the global `mp.prec`.
132
+
133
+ ## NaN handling
134
+
135
+ When the system matrix at a given frequency is numerically unstable, the solver
136
+ returns NaN rather than raising an exception. Use `np.nanargmax()` and
137
+ `np.nanmax()` in place of their standard counterparts to safely recover the
138
+ peak frequency and power without short-circuiting on degenerate bins.
139
+
140
+ For manual filtering, call `power()` or `autopower()` with `autonan=False` to
141
+ receive rough conditionality estimates alongside the periodogram. These
142
+ estimates are solver-specific: LDLT reports a diagonal-ratio estimate, while
143
+ the three Toeplitz solvers (`levinson`, `zohar`, and `bareiss`) return a
144
+ reflection-coefficient-based upper bound `(2*nterms + 1) * P`. The Toeplitz
145
+ estimates are generally much higher (and more reliable) for the same
146
+ frequencies, so threshold values should be chosen with the solver family in
147
+ mind.
148
+
149
+ ### Example usage of `tls` and `tlsf`
150
+
151
+ ```python
152
+ import numpy as np
153
+ import matplotlib.pyplot as plt
154
+ from toeplitz_ls import tls
155
+
156
+ rng = np.random.default_rng(seed=123)
157
+ N = 1000
158
+ t = np.sort(rng.uniform(0, 1000, size=N))
159
+ y = np.sin(50 * t) + 0.5 * np.sin(150 * t) + 1 + rng.poisson(size=N)
160
+
161
+ # Compute the generalized Scargle periodogram.
162
+ freq, r2 = tls.autopower(
163
+ t, y, dy=None,
164
+ fmax=12, # default value
165
+ nterms=1, # generalized Scargle periodogram
166
+ oversampling=5, # frequency density, relative to a dense, uniform FFT
167
+ backend="pswf43", # or "pswf21", "lra"
168
+ normalization="standard", # or "anova", "nll"
169
+ )
170
+
171
+ best_idx = np.nanargmax(r2)
172
+ best_freq = freq[best_idx]
173
+ best_power = r2[best_idx]
174
+
175
+ print(f"Peak frequency: {best_freq:.6g} (R^2 = {best_power:.6g})")
176
+
177
+ plt.figure(figsize=(12, 5))
178
+ plt.plot(freq, r2, label="degree = 1", color="red")
179
+ plt.axvline(best_freq, linestyle="--", color="black", alpha=0.7)
180
+ plt.xlabel("Frequency")
181
+ plt.ylabel("Coefficient of determination")
182
+ plt.legend()
183
+ plt.tight_layout()
184
+ plt.show()
185
+ ```
186
+
187
+ ### Example usage with an OGLE-BLAP light curve
188
+
189
+ ```python
190
+ from pathlib import Path
191
+ from tempfile import TemporaryDirectory
192
+ from urllib.request import urlretrieve
193
+
194
+ import numpy as np
195
+ from toeplitz_ls import tlsf, get_peaks
196
+
197
+ url = "https://www.astrouw.edu.pl/ogle/ogle4/OCVS/BLAP/phot/phot_ogle4/I/OGLE-BLAP-035.dat"
198
+
199
+ with TemporaryDirectory() as tmpdir:
200
+ data_path = Path(tmpdir) / "OGLE-BLAP-035.dat"
201
+ urlretrieve(url, str(data_path))
202
+ t, y, _dy = np.loadtxt(data_path, unpack=True)
203
+
204
+ t = t - t.min()
205
+
206
+ # BLAPs require high-frequency search. Ignore the photometric error estimates here.
207
+ freq, power, cond = tlsf.autopower(
208
+ t, y, dy=None,
209
+ fmax=100,
210
+ nterms=3,
211
+ oversampling=5,
212
+ solver="levinson", # or 'zohar', 'bareiss', 'ldlt', 'svd'
213
+ normalization="anova",
214
+ autonan=False,
215
+ )
216
+
217
+ peaks = get_peaks(freq, power, cond, threshold=10)
218
+ peaks.print(10)
219
+ ```
220
+
221
+ ## Development
222
+
223
+ The C and Python halves share one style: `.clang-format` and `ruff.toml` use the
224
+ same 160-column budget and 4-space indentation, so `make format` leaves both in
225
+ a state `make format-check` accepts.
226
+
227
+ ```console
228
+ make format # clang-format (src, include, tests) + ruff format/check (package, dispatch)
229
+ make format-check # the same, without writing
230
+ make generic # portable build for this machine's architecture
231
+ make native # build for this machine
232
+ make -C tests check
233
+ ```
234
+
235
+ Build artifacts (objects, staged wheel payloads, `.toolchains/`) live under
236
+ `.build/`. Nothing is committed to it.
237
+
238
+ ## Performance
239
+
240
+ The hot path is a blocked NuFFT sweep with vectorized transforms, deferred
241
+ permutations, and block-sized work arrays. On a modern
242
+ x86-64 CPU, a periodogram over roughly 10^4 frequencies takes on the order of
243
+ milliseconds; the IHS path is at least 3x cheaper. The benchmark harness lives
244
+ in `tests/`.
@@ -0,0 +1,96 @@
1
+ /* =============================================================================
2
+ * linalg.h — Public API for the precision-generic Toeplitz solvers.
3
+ *
4
+ * Declarations for all three precision variants produced by linalg.c. The
5
+ * float and double variants take GCC vector-extension batches, solving one
6
+ * independent system per SIMD lane. The double-double variant is scalar
7
+ * because its INTERNAL_VEC_LEN is 1.
8
+ * =============================================================================
9
+ */
10
+
11
+ #ifndef LINALG_H
12
+ #define LINALG_H
13
+
14
+ #include <nanofft.h> /* dd_t */
15
+ #include <stddef.h>
16
+
17
+ #ifdef __cplusplus
18
+ extern "C" {
19
+ #endif
20
+
21
+ /* =========================================================================
22
+ * float (tlsf_)
23
+ * ========================================================================= */
24
+
25
+ /** Dense real LDLT solver, single precision vector batch.
26
+ * Solves full row-major symmetric systems A x = b.
27
+ * Returns lane-wise Dmax/Dmin from the LDLT diagonal.
28
+ * Workspace: L length n*n; D, y, z length n each. */
29
+ TLS_API VECF tlsf_solve_ldlt(size_t n, const VECF *A, const VECF *b, VECF *x, VECF *L, VECF *D, VECF *y, VECF *z);
30
+
31
+ /** Levinson-Durbin recursion, single precision vector batch.
32
+ * Solves the Hermitian Toeplitz system T x = y.
33
+ * Returns a lane-wise upper condition bound from the reflection coefficients.
34
+ * Workspace: a_r, a_i, a_prev_r, a_prev_i — caller-owned, each length n. */
35
+ TLS_API VECF tlsf_solve_levinson(size_t n, const VECF *R_r, const VECF *R_i, const VECF *y_r, const VECF *y_i, VECF *x_r, VECF *x_i, VECF *a_r, VECF *a_i,
36
+ VECF *a_prev_r, VECF *a_prev_i);
37
+
38
+ /** Bareiss fast Cholesky solver, single precision vector batch.
39
+ * Returns the same lane-wise reflection-coefficient condition bound used by
40
+ * Levinson. Workspace: U_r, U_i length n*n; D, u_r, u_i, v_r, v_i, w_r, w_i
41
+ * length n each. */
42
+ TLS_API VECF tlsf_solve_bareiss(size_t n, const VECF *R_r, const VECF *R_i, const VECF *y_r, const VECF *y_i, VECF *x_r, VECF *x_i, VECF *U_r, VECF *U_i,
43
+ VECF *D, VECF *u_r, VECF *u_i, VECF *v_r, VECF *v_i, VECF *w_r, VECF *w_i);
44
+
45
+ /** Zohar recursion, single precision vector batch.
46
+ * Returns lane-wise zeros.
47
+ * Workspace: e_hat_r, e_hat_i, e_hat_prev_r, e_hat_prev_i — length n each.
48
+ * Note: R must have at least n+1 elements allocated (guard slot). */
49
+ TLS_API VECF tlsf_solve_zohar(size_t n, const VECF *R_r, const VECF *R_i, const VECF *y_r, const VECF *y_i, VECF *s_r, VECF *s_i, VECF *e_hat_r, VECF *e_hat_i,
50
+ VECF *e_hat_prev_r, VECF *e_hat_prev_i);
51
+
52
+ /** Symmetric Jacobi spectral solver, single precision vector batch.
53
+ * Solves full row-major symmetric systems A x = b.
54
+ * Returns lane-wise spectral condition estimates.
55
+ * Workspace: Q, S length n*n; D, y length n each. */
56
+ TLS_API VECF tlsf_solve_svd(size_t n, const VECF *A, const VECF *b, VECF *x, VECF *Q, VECF *S, VECF *D, VECF *y, VECF max_cond);
57
+
58
+ /* =========================================================================
59
+ * double (tls_)
60
+ * ========================================================================= */
61
+
62
+ TLS_API VEC tls_solve_ldlt(size_t n, const VEC *A, const VEC *b, VEC *x, VEC *L, VEC *D, VEC *y, VEC *z);
63
+
64
+ TLS_API VEC tls_solve_levinson(size_t n, const VEC *R_r, const VEC *R_i, const VEC *y_r, const VEC *y_i, VEC *x_r, VEC *x_i, VEC *a_r, VEC *a_i, VEC *a_prev_r,
65
+ VEC *a_prev_i);
66
+
67
+ TLS_API VEC tls_solve_bareiss(size_t n, const VEC *R_r, const VEC *R_i, const VEC *y_r, const VEC *y_i, VEC *x_r, VEC *x_i, VEC *U_r, VEC *U_i, VEC *D,
68
+ VEC *u_r, VEC *u_i, VEC *v_r, VEC *v_i, VEC *w_r, VEC *w_i);
69
+
70
+ TLS_API VEC tls_solve_zohar(size_t n, const VEC *R_r, const VEC *R_i, const VEC *y_r, const VEC *y_i, VEC *s_r, VEC *s_i, VEC *e_hat_r, VEC *e_hat_i,
71
+ VEC *e_hat_prev_r, VEC *e_hat_prev_i);
72
+
73
+ TLS_API VEC tls_solve_svd(size_t n, const VEC *A, const VEC *b, VEC *x, VEC *Q, VEC *S, VEC *D, VEC *y, VEC max_cond);
74
+
75
+ /* =========================================================================
76
+ * double-double (tlsdd_)
77
+ * ========================================================================= */
78
+
79
+ TLS_API dd_t tlsdd_solve_ldlt(size_t n, const dd_t *A, const dd_t *b, dd_t *x, dd_t *L, dd_t *D, dd_t *y, dd_t *z);
80
+
81
+ TLS_API dd_t tlsdd_solve_levinson(size_t n, const dd_t *R_r, const dd_t *R_i, const dd_t *y_r, const dd_t *y_i, dd_t *x_r, dd_t *x_i, dd_t *a_r, dd_t *a_i,
82
+ dd_t *a_prev_r, dd_t *a_prev_i);
83
+
84
+ TLS_API dd_t tlsdd_solve_bareiss(size_t n, const dd_t *R_r, const dd_t *R_i, const dd_t *y_r, const dd_t *y_i, dd_t *x_r, dd_t *x_i, dd_t *U_r, dd_t *U_i,
85
+ dd_t *D, dd_t *u_r, dd_t *u_i, dd_t *v_r, dd_t *v_i, dd_t *w_r, dd_t *w_i);
86
+
87
+ TLS_API dd_t tlsdd_solve_zohar(size_t n, const dd_t *R_r, const dd_t *R_i, const dd_t *y_r, const dd_t *y_i, dd_t *s_r, dd_t *s_i, dd_t *e_hat_r, dd_t *e_hat_i,
88
+ dd_t *e_hat_prev_r, dd_t *e_hat_prev_i);
89
+
90
+ TLS_API dd_t tlsdd_solve_svd(size_t n, const dd_t *A, const dd_t *b, dd_t *x, dd_t *Q, dd_t *S, dd_t *D, dd_t *y, dd_t max_cond);
91
+
92
+ #ifdef __cplusplus
93
+ }
94
+ #endif
95
+
96
+ #endif /* LINALG_H */