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.
- toeplitz_ls-1.0.0rc1/LICENSE +21 -0
- toeplitz_ls-1.0.0rc1/PKG-INFO +269 -0
- toeplitz_ls-1.0.0rc1/README.md +244 -0
- toeplitz_ls-1.0.0rc1/include/linalg.h +96 -0
- toeplitz_ls-1.0.0rc1/include/nanofft.h +483 -0
- toeplitz_ls-1.0.0rc1/include/nanofft_exp_coeffs.h +42 -0
- toeplitz_ls-1.0.0rc1/include/nanofft_precision.h +147 -0
- toeplitz_ls-1.0.0rc1/include/nanofft_vecmath.h +144 -0
- toeplitz_ls-1.0.0rc1/include/nufft1.h +63 -0
- toeplitz_ls-1.0.0rc1/include/scaling_generic.h +23 -0
- toeplitz_ls-1.0.0rc1/include/tls.h +85 -0
- toeplitz_ls-1.0.0rc1/include/tls_cpu.h +69 -0
- toeplitz_ls-1.0.0rc1/include/tls_export.h +39 -0
- toeplitz_ls-1.0.0rc1/include/tls_internal.h +51 -0
- toeplitz_ls-1.0.0rc1/include/tls_platform.h +165 -0
- toeplitz_ls-1.0.0rc1/include/tls_tuning.h +73 -0
- toeplitz_ls-1.0.0rc1/include/utils.h +40 -0
- toeplitz_ls-1.0.0rc1/pyproject.toml +17 -0
- toeplitz_ls-1.0.0rc1/src/chi2per.c +2219 -0
- toeplitz_ls-1.0.0rc1/src/cpu_features.c +196 -0
- toeplitz_ls-1.0.0rc1/src/linalg.c +685 -0
- toeplitz_ls-1.0.0rc1/src/nanofft.c +1036 -0
- toeplitz_ls-1.0.0rc1/src/nufft1.c +1250 -0
- toeplitz_ls-1.0.0rc1/src/probe_arm64.c +36 -0
- toeplitz_ls-1.0.0rc1/src/tuning.c +55 -0
- toeplitz_ls-1.0.0rc1/src/utils.c +273 -0
- toeplitz_ls-1.0.0rc1/tls_source_build.py +231 -0
- toeplitz_ls-1.0.0rc1/toeplitz_ls/__init__.py +26 -0
- toeplitz_ls-1.0.0rc1/toeplitz_ls/_dispatch.py +379 -0
- toeplitz_ls-1.0.0rc1/toeplitz_ls/_fastchi2.py +705 -0
- toeplitz_ls-1.0.0rc1/toeplitz_ls/_ihs.py +322 -0
- 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 */
|