toeplitz-ls 1.0.0rc1__py3-none-win_amd64.whl

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.
@@ -0,0 +1,26 @@
1
+ """Python interface for the Toeplitz least-squares FastChi2 library."""
2
+
3
+ from . import _dispatch
4
+ from ._fastchi2 import DD, tls, tlsdd, tlsf, trim_mantissa
5
+ from ._ihs import ihs, ihsdd, ihsf
6
+ from .utils import Peak, Peaks, get_peaks
7
+
8
+ __version__ = "1.0.0rc1"
9
+
10
+ #: Manifest entry of the microarchitecture variant this process loaded.
11
+ __dispatch__ = _dispatch.selected()
12
+
13
+ __all__ = [
14
+ "DD",
15
+ "tlsf",
16
+ "tls",
17
+ "tlsdd",
18
+ "ihsf",
19
+ "ihs",
20
+ "ihsdd",
21
+ "trim_mantissa",
22
+ "Peak",
23
+ "Peaks",
24
+ "get_peaks",
25
+ "__version__",
26
+ ]
@@ -0,0 +1,379 @@
1
+ """Import-time selection of the native library variant.
2
+
3
+ A wheel ships one shared object per microarchitecture level (see
4
+ ``dispatch/variants.py`` in the source tree) plus ``_lib/manifest.json``
5
+ describing them. This module looks at the CPU it is running on, picks the
6
+ widest variant that CPU can execute, and loads it. The choice is made once,
7
+ at import, so a periodogram call pays nothing for the dispatch.
8
+
9
+ Fallbacks, in order:
10
+
11
+ * ``TOEPLITZ_LS_DISPATCH=<variant>`` forces a variant (it must be supported by
12
+ the CPU, otherwise the import fails instead of crashing later with SIGILL);
13
+ * ``TOEPLITZ_LS_DISPATCH=list`` prints the shipped variants and continues with
14
+ automatic selection;
15
+ * a source build (``make native`` / ``make generic``) has no ``_lib`` directory
16
+ and keeps loading the single ``toeplitz_ls/tls.so`` next to this file.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import ctypes
22
+ import json
23
+ import os
24
+ import platform
25
+ from pathlib import Path
26
+
27
+ HERE = Path(__file__).resolve().parent
28
+ LIB_DIR = HERE / "_lib"
29
+ MANIFEST_PATH = LIB_DIR / "manifest.json"
30
+ LEGACY_PATH = HERE / "tls.so"
31
+
32
+ ENV = "TOEPLITZ_LS_DISPATCH"
33
+
34
+ _LIB = None
35
+ _SELECTED = None
36
+
37
+
38
+ # ---------------------------------------------------------------------------
39
+ # CPU feature probing
40
+ # ---------------------------------------------------------------------------
41
+ def _read_proc_cpuinfo_flags():
42
+ flags = set()
43
+ try:
44
+ with open("/proc/cpuinfo", "r", encoding="utf-8", errors="ignore") as handle:
45
+ for line in handle:
46
+ key, sep, value = line.partition(":")
47
+ if sep and key.strip().lower() in ("flags", "features"):
48
+ flags.update(value.split())
49
+ break
50
+ except OSError:
51
+ pass
52
+ return flags
53
+
54
+
55
+ def _prctl_sve_vector_length():
56
+ """SVE vector length in bytes via prctl(PR_SVE_GET_VL), or 0."""
57
+ try:
58
+ libc = ctypes.CDLL(None, use_errno=True)
59
+ rc = libc.prctl(51, 0, 0, 0, 0) # PR_SVE_GET_VL
60
+ except (OSError, AttributeError):
61
+ return 0
62
+ if rc <= 0:
63
+ return 0
64
+ return rc & 0xFFFF
65
+
66
+
67
+ def _windows_features():
68
+ features = set()
69
+ try:
70
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) # type: ignore[attr-defined]
71
+ present = kernel32.IsProcessorFeaturePresent
72
+ present.argtypes = [ctypes.c_uint]
73
+ present.restype = ctypes.c_int
74
+ except (OSError, AttributeError):
75
+ return features
76
+ # Values from the Windows SDK's winnt.h (PF_*_INSTRUCTIONS_AVAILABLE).
77
+ table = {
78
+ 36: "ssse3",
79
+ 37: "sse4_1",
80
+ 38: "sse4_2",
81
+ 39: "avx",
82
+ 40: "avx2",
83
+ 41: "avx512f",
84
+ 19: "asimd",
85
+ 46: "sve",
86
+ }
87
+ for bit, name in table.items():
88
+ if present(bit):
89
+ features.add(name)
90
+ return features
91
+
92
+
93
+ def _macos_sysctl(name):
94
+ try:
95
+ libc = ctypes.CDLL(None)
96
+ libc.sysctlbyname.argtypes = [
97
+ ctypes.c_char_p,
98
+ ctypes.c_void_p,
99
+ ctypes.POINTER(ctypes.c_size_t),
100
+ ctypes.c_void_p,
101
+ ctypes.c_size_t,
102
+ ]
103
+ size = ctypes.c_size_t(0)
104
+ if libc.sysctlbyname(name.encode(), None, ctypes.byref(size), None, 0) != 0 or size.value == 0:
105
+ return ""
106
+ buf = ctypes.create_string_buffer(size.value)
107
+ if libc.sysctlbyname(name.encode(), buf, ctypes.byref(size), None, 0) != 0:
108
+ return ""
109
+ return buf.value.decode("ascii", "ignore")
110
+ except (OSError, AttributeError):
111
+ return ""
112
+
113
+
114
+ def _macos_features():
115
+ features = set()
116
+ if platform.machine() == "arm64":
117
+ features.add("asimd") # Apple silicon always has NEON, never SVE
118
+ return features
119
+ leaf = _macos_sysctl("machdep.cpu.features").split()
120
+ leaf7 = _macos_sysctl("machdep.cpu.leaf7_features").split()
121
+ # Both sysctls are space-separated CPUID flag names; match whole tokens
122
+ # ("AVX" must not fire on "AVX2.0", and macOS reports "AVX", not "AVX1.0").
123
+ tokens = set(leaf) | set(leaf7)
124
+ table = {
125
+ "SSE4.1": ("sse4_1",),
126
+ "SSE4.2": ("sse4_2",),
127
+ "SSSE3": ("ssse3",),
128
+ "POPCNT": ("popcnt",),
129
+ "CX16": ("cx16",),
130
+ "LAHF": ("lahf_lm",),
131
+ "AVX": ("avx",),
132
+ "AVX1.0": ("avx",),
133
+ "XSAVE": ("xsave",),
134
+ "F16C": ("f16c",),
135
+ "AVX2": ("avx2",),
136
+ "AVX2.0": ("avx2",),
137
+ "AVX512F": ("avx512f",),
138
+ "AVX512BW": ("avx512bw",),
139
+ "AVX512CD": ("avx512cd",),
140
+ "AVX512DQ": ("avx512dq",),
141
+ "AVX512VL": ("avx512vl",),
142
+ "BMI1": ("bmi1",),
143
+ "BMI2": ("bmi2",),
144
+ "FMA": ("fma",),
145
+ "ABM": ("abm",),
146
+ "LZCNT": ("lzcnt",),
147
+ "MOVBE": ("movbe",),
148
+ }
149
+ for token, names in table.items():
150
+ if token in tokens:
151
+ features.update(names)
152
+ return features
153
+
154
+
155
+ #: Bit order of the mask returned by the library's ``tls_cpu_features()``
156
+ #: (include/tls_cpu.h). Change both together.
157
+ _FEATURE_BITS = (
158
+ "sse4_1",
159
+ "sse4_2",
160
+ "ssse3",
161
+ "popcnt",
162
+ "cx16",
163
+ "lahf_lm",
164
+ "avx",
165
+ "xsave",
166
+ "avx2",
167
+ "fma",
168
+ "bmi1",
169
+ "bmi2",
170
+ "f16c",
171
+ "lzcnt",
172
+ "movbe",
173
+ "avx512f",
174
+ "avx512bw",
175
+ "avx512cd",
176
+ "avx512dq",
177
+ "avx512vl",
178
+ "asimd",
179
+ "sve",
180
+ "dotprod",
181
+ "i8mm",
182
+ "bf16",
183
+ )
184
+
185
+
186
+ def _probe_features(manifest):
187
+ """Feature names reported by the baseline library's own CPUID/HWCAP probe.
188
+
189
+ This is the authoritative answer: it is the same CPU the code will run on,
190
+ and the probe also checks that the OS enabled the AVX/AVX-512 state. The
191
+ baseline library is always shipped and always safe to load, so asking it
192
+ before choosing a wider variant costs one dlopen.
193
+ """
194
+ variants = manifest.get("variants") or []
195
+ if not variants:
196
+ return set()
197
+ baseline = variants[manifest.get("baseline", 0)]
198
+ try:
199
+ probe_lib = ctypes.CDLL(str(LIB_DIR / baseline["file"]))
200
+ probe = probe_lib.tls_cpu_features
201
+ probe.argtypes = []
202
+ probe.restype = ctypes.c_ulonglong
203
+ mask = int(probe())
204
+ except (OSError, AttributeError):
205
+ return set()
206
+ return {name for bit, name in enumerate(_FEATURE_BITS) if mask >> bit & 1}
207
+
208
+
209
+ def host_features(manifest=None):
210
+ """Set of feature names this CPU can execute (OS hints + the library probe)."""
211
+ features = _probe_features(manifest) if manifest is not None else set()
212
+ machine = platform.machine().lower()
213
+ system = platform.system().lower()
214
+
215
+ if system == "windows":
216
+ features |= _windows_features()
217
+ if machine in ("arm64", "aarch64"):
218
+ features.add("asimd") # mandatory on AArch64
219
+ return features
220
+
221
+ if system == "darwin":
222
+ features |= _macos_features()
223
+ return features
224
+
225
+ flags = set(_read_proc_cpuinfo_flags())
226
+ # Names differ between the Linux flag list and the ISA level names.
227
+ if "abm" in flags:
228
+ flags.add("lzcnt")
229
+ if "sve" in flags:
230
+ vector_bytes = _prctl_sve_vector_length()
231
+ if vector_bytes:
232
+ flags.add("sve_vl:%d" % vector_bytes)
233
+ if machine in ("aarch64", "arm64"):
234
+ flags.add("asimd") # mandatory on AArch64, even when cpuinfo omits it
235
+ return features | flags
236
+
237
+
238
+ def _complete_sve_length(manifest, features):
239
+ """Ask the baseline library for the SVE vector length when the OS will not.
240
+
241
+ Linux answers through prctl and needs no help; Windows publishes only an
242
+ "SVE present" bit, so the length comes from the baseline library's `cntb`
243
+ probe, which is safe to call as soon as that bit is set.
244
+ """
245
+ if "sve" not in features or any(f.startswith("sve_vl:") for f in features):
246
+ return
247
+ variants = manifest.get("variants") or []
248
+ baseline = variants[manifest.get("baseline", 0)] if variants else None
249
+ if baseline is None:
250
+ return
251
+ try:
252
+ probe_lib = ctypes.CDLL(str(LIB_DIR / baseline["file"]))
253
+ probe = probe_lib.tls_probe_sve_vector_length
254
+ probe.argtypes = []
255
+ probe.restype = ctypes.c_ulong
256
+ length = int(probe())
257
+ except (OSError, AttributeError):
258
+ return
259
+ if length > 0:
260
+ features.add("sve_vl:%d" % length)
261
+
262
+
263
+ def _has_any(alternatives, features):
264
+ """True if one of `alternatives` is present; a nested group is itself OR-ed.
265
+
266
+ Manifests written by older builds carry level descriptions such as
267
+ ("cx16", "lahf_lm", ...) whose members were meant to be *all* required; a
268
+ nested alternative ("abm", "lzcnt") is the one genuine either-or. Treating
269
+ a nested sequence as another OR group keeps such manifests readable instead
270
+ of raising "unhashable type" on a set lookup.
271
+ """
272
+ for alt in alternatives:
273
+ if isinstance(alt, (list, tuple)):
274
+ if _has_any(alt, features):
275
+ return True
276
+ elif alt in features:
277
+ return True
278
+ return False
279
+
280
+
281
+ def _satisfied(requires, features):
282
+ return all(_has_any(group, features) for group in requires)
283
+
284
+
285
+ # ---------------------------------------------------------------------------
286
+ # Manifest and selection
287
+ # ---------------------------------------------------------------------------
288
+ def load_manifest():
289
+ try:
290
+ with open(MANIFEST_PATH, "r", encoding="utf-8") as handle:
291
+ return json.load(handle)
292
+ except OSError:
293
+ return None
294
+
295
+
296
+ def _select(manifest, features, forced=None):
297
+ variants = manifest.get("variants") or []
298
+ if not variants:
299
+ raise RuntimeError("%s lists no variants" % MANIFEST_PATH)
300
+ if forced:
301
+ for entry in variants:
302
+ if entry["name"] == forced:
303
+ if not _satisfied(entry.get("requires", []), features):
304
+ raise RuntimeError(
305
+ "TOEPLITZ_LS_DISPATCH=%s is not supported by this CPU (missing %s); "
306
+ "shipped variants: %s" % (forced, _missing(entry.get("requires", []), features), ", ".join(v["name"] for v in variants))
307
+ )
308
+ return entry
309
+ raise RuntimeError("TOEPLITZ_LS_DISPATCH=%s is not shipped; available: %s" % (forced, ", ".join(v["name"] for v in variants)))
310
+ for entry in reversed(variants):
311
+ if _satisfied(entry.get("requires", []), features):
312
+ return entry
313
+ return variants[manifest.get("baseline", 0)]
314
+
315
+
316
+ def _label(group):
317
+ return "|".join(str(item) for item in group)
318
+
319
+
320
+ def _missing(requires, features):
321
+ return ", ".join(_label(group) for group in requires if not _has_any(group, features))
322
+
323
+
324
+ def _describe(manifest, features):
325
+ for entry in manifest.get("variants", []):
326
+ ok = _satisfied(entry.get("requires", []), features)
327
+ print(" %-22s %s%s" % (entry["name"], entry["file"], "" if ok else " (unsupported on this CPU)"))
328
+
329
+
330
+ def load():
331
+ """Return the shared library for this CPU, loading it once."""
332
+ global _LIB, _SELECTED
333
+ if _LIB is not None:
334
+ return _LIB
335
+
336
+ forced = os.environ.get(ENV, "").strip()
337
+ manifest = load_manifest()
338
+ if manifest is None:
339
+ if not LEGACY_PATH.exists():
340
+ raise FileNotFoundError("%s is missing. Build the package from source with 'make native' (or install a wheel) before importing it." % LEGACY_PATH)
341
+ _LIB = ctypes.CDLL(str(LEGACY_PATH))
342
+ _SELECTED = {"name": "source-build", "file": LEGACY_PATH.name, "requires": []}
343
+ return _LIB
344
+
345
+ features = host_features(manifest)
346
+ _complete_sve_length(manifest, features)
347
+ if forced.lower() in ("list", "help"):
348
+ print("Toeplitz-LS shipped variants (%s):" % platform.machine())
349
+ _describe(manifest, features)
350
+ forced = ""
351
+
352
+ entry = _select(manifest, features, forced or None)
353
+ path = LIB_DIR / entry["file"]
354
+ lib = ctypes.CDLL(str(path))
355
+ _LIB = lib
356
+ _SELECTED = entry
357
+ return lib
358
+
359
+
360
+ def selected():
361
+ """Manifest entry of the loaded variant (or a synthetic source-build one)."""
362
+ if _SELECTED is None:
363
+ load()
364
+ return _SELECTED
365
+
366
+
367
+ def sve_vector_length():
368
+ """Hardware SVE vector length in bytes, probing the loaded library."""
369
+ lib = load()
370
+ try:
371
+ probe = lib.tls_probe_sve_vector_length
372
+ except AttributeError:
373
+ return 0
374
+ probe.argtypes = []
375
+ probe.restype = ctypes.c_ulong
376
+ return int(probe())
377
+
378
+
379
+ __all__ = ["load", "selected", "host_features", "sve_vector_length", "load_manifest", "selected"]