dampmeter 1.0.0__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.
@@ -0,0 +1,25 @@
1
+ Creative Commons Attribution 4.0 International (CC BY 4.0)
2
+
3
+ Copyright (c) 2026 tygtDc, Deep Research; Ma Ka Po
4
+
5
+ This work is licensed under the Creative Commons Attribution 4.0
6
+ International License.
7
+
8
+ You are free to:
9
+
10
+ Share — copy and redistribute the material in any medium or format
11
+ Adapt — remix, transform, and build upon the material for any purpose,
12
+ even commercially.
13
+
14
+ Under the following terms:
15
+
16
+ Attribution — You must give appropriate credit, provide a link to the
17
+ license, and indicate if changes were made. You may do so in any
18
+ reasonable manner, but not in any way that suggests the licensor
19
+ endorses you or your use.
20
+
21
+ No additional restrictions — You may not apply legal terms or
22
+ technological measures that legally restrict others from doing anything
23
+ the license permits.
24
+
25
+ Full license text: https://creativecommons.org/licenses/by/4.0/legalcode
@@ -0,0 +1,119 @@
1
+ Metadata-Version: 2.4
2
+ Name: dampmeter
3
+ Version: 1.0.0
4
+ Summary: IDV damping caliper: measure a system's intrinsic relaxation time tau (gamma = 1/tau) from a single scalar time series — four-test convergence + shuffle null, KB-RAM / millisecond class, built for edge devices
5
+ Author: Ma Ka Po
6
+ Author-email: "tygtDc, Deep Research" <drtygtdc@gmail.com>
7
+ License: CC BY 4.0
8
+ Keywords: damping,relaxation time,time series,nonlinear dynamics,autocorrelation,distance correlation,ring-down,edge computing,structural health monitoring,attractor
9
+ Classifier: Development Status :: 5 - Production/Stable
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: License :: Other/Proprietary License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Scientific/Engineering :: Physics
18
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
19
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: numpy>=1.24
24
+ Requires-Dist: scipy>=1.10
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7; extra == "dev"
27
+ Dynamic: license-file
28
+
29
+ # dampmeter — IDV individual damping caliper
30
+
31
+ **Measure a system's intrinsic relaxation time τ (γ = 1/τ) from a single scalar time series.**
32
+ Four independent estimators, convergence-as-identity-check, shuffle-null control.
33
+ KB-RAM / millisecond class — built for edge devices.
34
+
35
+ ```python
36
+ import dampmeter as dm
37
+
38
+ est = dm.measure(x, dt=1.0) # x = one scalar series, stationary window
39
+ est.tau # damping time constant, in units of dt
40
+ est.gamma # 1/tau
41
+ est.converged # True when >=3 estimators agree within ±30% of the median
42
+ ```
43
+
44
+ ## What it measures (and what it does not)
45
+
46
+ | | |
47
+ |---|---|
48
+ | ✅ **Effective damping time τ** | how fast perturbations decay inside a stable regime (effective linear relaxation) |
49
+ | ✅ **Stability of τ** | convergence across independent estimators + a shuffle null — "this constant is really there", not "the fit looks good" |
50
+ | ❌ **Mechanism** | γ is *effective* only; decomposing it (radiative vs wave drag vs friction…) needs budget methods |
51
+ | ❌ **Potential-well stiffness** | stiffness is curvature (ω₀²), a different physical quantity — this package measures dissipation, not stiffness |
52
+ | ❌ **Sign of degradation** | "damage → damping" has no universal sign: defect-size axis (τ↑) and wear/life axis (τ↓) can go opposite ways — always specify the axis before interpreting trends |
53
+
54
+ ## Estimators
55
+
56
+ | Method | What it does |
57
+ |---|---|
58
+ | `tau1_acf` | autocorrelation e-fold decay |
59
+ | `tau2_dcor` | distance-correlation e-fold (nonlinear, shift-invariant) |
60
+ | `tau3_ringdown` | impulse-conditioned ring-down decay R(k) |
61
+ | `tau4_recovery` | post-drop recovery time (auxiliary; right-censoring prone — never evidence alone) |
62
+
63
+ Convergence rule: at least 3 of the primary methods within ±30% of the median ⇒ individual damping established. Two ring-down calibers are provided and deliberately kept separate:
64
+
65
+ - `ringdown_conditional` — impulse-conditioned decay (the validated IDV estimator);
66
+ - `ringdown_envelope` — analytic-envelope decay for band-passed oscillatory signals, using the **Hilbert analytic envelope** with the normalized MAD event threshold `median|env − median(env)| × 1.4826`.
67
+ Known traps these are built against: `|band-passed|` as the "envelope" quantizes τ to the oscillation half-period; `median(env) × 1.4826` is the wrong MAD (threshold lands near ~5σ, almost nothing crosses it).
68
+
69
+ ## Minimum data (2,800-bootstrap characterization, ±30% hit rate)
70
+
71
+ | Samples | Hit rate | Verdict |
72
+ |---|---|---|
73
+ | 20 | 13% (τ underestimated ~2×) | ❌ hard floor — do not use |
74
+ | ~180 | 57% | ⚠️ coarse tier |
75
+ | **~610** | **81.5%** | ✅ reliable tier |
76
+ | ~1,220 | 97% | ✅ stable |
77
+
78
+ The impulse ring-down method needs more: ≥40 pulses ≈ 1,500 samples for 65%.
79
+ Compute: single core seconds (2,800 bootstraps), RAM KB-class, per-test milliseconds — 6–9 orders of magnitude cheaper than reanalysis-budget approaches.
80
+
81
+ ## Null control (do not skip)
82
+
83
+ ```python
84
+ tau_null = dm.shuffle_null_ringdown(x, blocks=years) # shuffle within blocks
85
+ ```
86
+
87
+ If the ring-down τ does **not** collapse after temporal structure is destroyed, you are reading a mathematical necessity (trend / mean offset), not physics — invalidate the estimate.
88
+
89
+ ## Pitfalls
90
+
91
+ - **Detrend first** (fit the trend on the anomaly, not the raw series). A mean offset lifts the ACF plateau so the curve never reaches 1/e (NaN) — the dCor estimate stays shift-invariant and can help locate the problem.
92
+ - **Stationary window + effective linear relaxation** are the working assumptions.
93
+ - **Short-lived systems** (e.g. ~10-day storms) cannot pass the 610-sample floor.
94
+ - **Do not transplant thresholds across domains** (geometric cutoffs, event quantiles): re-derive per domain with sensitivity checks, and calibrate on a ground-truth domain first.
95
+
96
+ ## Validation status (honest)
97
+
98
+ - τ convergence (3 methods: 11.28 / 10.81 / 13.32 → τ ≈ 12.3 days) and shuffle-null collapse (τ → 0.9) have been demonstrated on **one physical system** (stratospheric polar vortex, 2,867 daily samples). Ring-down caliber applications exist on two more domains (bearing vibration, ECG), single-caliber only.
99
+ - Cross-domain τ convergence replication is pending — treat new domains as unvalidated until you run convergence + null there.
100
+
101
+ ## Install
102
+
103
+ ```bash
104
+ pip install dampmeter
105
+ ```
106
+
107
+ Pure numpy + scipy. Python ≥ 3.9.
108
+
109
+ ## References
110
+
111
+ Part of the Ô-HAT dual-operator measurement primitive (IDV caliper + T blind-state gatekeeper). Method details, usage boundaries and the engineering interface table: `project/ohat_framework/note-dual-operator-idv-t.md` (framework v3.7, §3.12).
112
+
113
+ ## Authors
114
+
115
+ tygtDc, Deep Research (correspondence: drtygtdc@gmail.com) · Ma Ka Po
116
+
117
+ ## License
118
+
119
+ CC BY 4.0 — free to use, adapt and commercialize with attribution.
@@ -0,0 +1,91 @@
1
+ # dampmeter — IDV individual damping caliper
2
+
3
+ **Measure a system's intrinsic relaxation time τ (γ = 1/τ) from a single scalar time series.**
4
+ Four independent estimators, convergence-as-identity-check, shuffle-null control.
5
+ KB-RAM / millisecond class — built for edge devices.
6
+
7
+ ```python
8
+ import dampmeter as dm
9
+
10
+ est = dm.measure(x, dt=1.0) # x = one scalar series, stationary window
11
+ est.tau # damping time constant, in units of dt
12
+ est.gamma # 1/tau
13
+ est.converged # True when >=3 estimators agree within ±30% of the median
14
+ ```
15
+
16
+ ## What it measures (and what it does not)
17
+
18
+ | | |
19
+ |---|---|
20
+ | ✅ **Effective damping time τ** | how fast perturbations decay inside a stable regime (effective linear relaxation) |
21
+ | ✅ **Stability of τ** | convergence across independent estimators + a shuffle null — "this constant is really there", not "the fit looks good" |
22
+ | ❌ **Mechanism** | γ is *effective* only; decomposing it (radiative vs wave drag vs friction…) needs budget methods |
23
+ | ❌ **Potential-well stiffness** | stiffness is curvature (ω₀²), a different physical quantity — this package measures dissipation, not stiffness |
24
+ | ❌ **Sign of degradation** | "damage → damping" has no universal sign: defect-size axis (τ↑) and wear/life axis (τ↓) can go opposite ways — always specify the axis before interpreting trends |
25
+
26
+ ## Estimators
27
+
28
+ | Method | What it does |
29
+ |---|---|
30
+ | `tau1_acf` | autocorrelation e-fold decay |
31
+ | `tau2_dcor` | distance-correlation e-fold (nonlinear, shift-invariant) |
32
+ | `tau3_ringdown` | impulse-conditioned ring-down decay R(k) |
33
+ | `tau4_recovery` | post-drop recovery time (auxiliary; right-censoring prone — never evidence alone) |
34
+
35
+ Convergence rule: at least 3 of the primary methods within ±30% of the median ⇒ individual damping established. Two ring-down calibers are provided and deliberately kept separate:
36
+
37
+ - `ringdown_conditional` — impulse-conditioned decay (the validated IDV estimator);
38
+ - `ringdown_envelope` — analytic-envelope decay for band-passed oscillatory signals, using the **Hilbert analytic envelope** with the normalized MAD event threshold `median|env − median(env)| × 1.4826`.
39
+ Known traps these are built against: `|band-passed|` as the "envelope" quantizes τ to the oscillation half-period; `median(env) × 1.4826` is the wrong MAD (threshold lands near ~5σ, almost nothing crosses it).
40
+
41
+ ## Minimum data (2,800-bootstrap characterization, ±30% hit rate)
42
+
43
+ | Samples | Hit rate | Verdict |
44
+ |---|---|---|
45
+ | 20 | 13% (τ underestimated ~2×) | ❌ hard floor — do not use |
46
+ | ~180 | 57% | ⚠️ coarse tier |
47
+ | **~610** | **81.5%** | ✅ reliable tier |
48
+ | ~1,220 | 97% | ✅ stable |
49
+
50
+ The impulse ring-down method needs more: ≥40 pulses ≈ 1,500 samples for 65%.
51
+ Compute: single core seconds (2,800 bootstraps), RAM KB-class, per-test milliseconds — 6–9 orders of magnitude cheaper than reanalysis-budget approaches.
52
+
53
+ ## Null control (do not skip)
54
+
55
+ ```python
56
+ tau_null = dm.shuffle_null_ringdown(x, blocks=years) # shuffle within blocks
57
+ ```
58
+
59
+ If the ring-down τ does **not** collapse after temporal structure is destroyed, you are reading a mathematical necessity (trend / mean offset), not physics — invalidate the estimate.
60
+
61
+ ## Pitfalls
62
+
63
+ - **Detrend first** (fit the trend on the anomaly, not the raw series). A mean offset lifts the ACF plateau so the curve never reaches 1/e (NaN) — the dCor estimate stays shift-invariant and can help locate the problem.
64
+ - **Stationary window + effective linear relaxation** are the working assumptions.
65
+ - **Short-lived systems** (e.g. ~10-day storms) cannot pass the 610-sample floor.
66
+ - **Do not transplant thresholds across domains** (geometric cutoffs, event quantiles): re-derive per domain with sensitivity checks, and calibrate on a ground-truth domain first.
67
+
68
+ ## Validation status (honest)
69
+
70
+ - τ convergence (3 methods: 11.28 / 10.81 / 13.32 → τ ≈ 12.3 days) and shuffle-null collapse (τ → 0.9) have been demonstrated on **one physical system** (stratospheric polar vortex, 2,867 daily samples). Ring-down caliber applications exist on two more domains (bearing vibration, ECG), single-caliber only.
71
+ - Cross-domain τ convergence replication is pending — treat new domains as unvalidated until you run convergence + null there.
72
+
73
+ ## Install
74
+
75
+ ```bash
76
+ pip install dampmeter
77
+ ```
78
+
79
+ Pure numpy + scipy. Python ≥ 3.9.
80
+
81
+ ## References
82
+
83
+ Part of the Ô-HAT dual-operator measurement primitive (IDV caliper + T blind-state gatekeeper). Method details, usage boundaries and the engineering interface table: `project/ohat_framework/note-dual-operator-idv-t.md` (framework v3.7, §3.12).
84
+
85
+ ## Authors
86
+
87
+ tygtDc, Deep Research (correspondence: drtygtdc@gmail.com) · Ma Ka Po
88
+
89
+ ## License
90
+
91
+ CC BY 4.0 — free to use, adapt and commercialize with attribution.
@@ -0,0 +1,46 @@
1
+ [build-system]
2
+ requires = ["setuptools>=64", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "dampmeter"
7
+ version = "1.0.0"
8
+ description = "IDV damping caliper: measure a system's intrinsic relaxation time tau (gamma = 1/tau) from a single scalar time series — four-test convergence + shuffle null, KB-RAM / millisecond class, built for edge devices"
9
+ readme = "README.md"
10
+ license = {text = "CC BY 4.0"}
11
+ authors = [
12
+ {name = "tygtDc, Deep Research", email = "drtygtdc@gmail.com"},
13
+ {name = "Ma Ka Po"},
14
+ ]
15
+ keywords = [
16
+ "damping", "relaxation time", "time series", "nonlinear dynamics",
17
+ "autocorrelation", "distance correlation", "ring-down", "edge computing",
18
+ "structural health monitoring", "attractor",
19
+ ]
20
+ classifiers = [
21
+ "Development Status :: 5 - Production/Stable",
22
+ "Intended Audience :: Science/Research",
23
+ "License :: Other/Proprietary License",
24
+ "Programming Language :: Python :: 3",
25
+ "Programming Language :: Python :: 3.9",
26
+ "Programming Language :: Python :: 3.10",
27
+ "Programming Language :: Python :: 3.11",
28
+ "Programming Language :: Python :: 3.12",
29
+ "Topic :: Scientific/Engineering :: Physics",
30
+ "Topic :: Scientific/Engineering :: Information Analysis",
31
+ "Topic :: Scientific/Engineering :: Mathematics",
32
+ ]
33
+ requires-python = ">=3.9"
34
+ dependencies = [
35
+ "numpy>=1.24",
36
+ "scipy>=1.10",
37
+ ]
38
+
39
+ [project.optional-dependencies]
40
+ dev = ["pytest>=7"]
41
+
42
+ [tool.setuptools.packages.find]
43
+ where = ["src"]
44
+
45
+ [tool.setuptools.package-data]
46
+ dampmeter = ["py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,61 @@
1
+ """dampmeter — IDV individual damping caliper.
2
+
3
+ Measure a system's intrinsic relaxation (damping) time constant ``tau``
4
+ from a single scalar time series, with four independent estimators,
5
+ convergence-as-identity-check, and a shuffle null control.
6
+
7
+ Terminology: this package measures the *effective damping* (dissipative
8
+ time constant tau, gamma = 1/tau) — NOT the potential-well stiffness
9
+ (curvature, omega0^2). The two are different physical quantities.
10
+
11
+ The output is an *effective* gamma only: it says "how much, and how
12
+ stable", never "which mechanism". Sign interpretation of damping change
13
+ is axis-dependent (defect-size axis vs wear/life axis can go opposite
14
+ directions) — always specify the axis before interpreting trends.
15
+
16
+ Caliber note: the ring-down envelope estimator uses the Hilbert
17
+ analytic envelope with the normalized MAD threshold
18
+ median|env - median(env)| * 1.4826. Using |band-passed| as the envelope
19
+ measures the oscillation half-period instead of damping decay — do not
20
+ swap the calibers.
21
+ """
22
+ from ._core import (
23
+ EFOLD,
24
+ HARD_FLOOR_POINTS,
25
+ COARSE_MIN_POINTS,
26
+ RECOMMENDED_MIN_POINTS,
27
+ DampingEstimate,
28
+ acf_curve,
29
+ acf_efold,
30
+ check_data_length,
31
+ dcor,
32
+ dcor_efold,
33
+ efold_from_curve,
34
+ measure,
35
+ recovery_tau,
36
+ )
37
+ from ._ringdown import ringdown_conditional, ringdown_envelope
38
+ from ._null import phase_surrogate_taus, shuffle_null_ringdown
39
+
40
+ __version__ = "1.0.0"
41
+
42
+ __all__ = [
43
+ "EFOLD",
44
+ "HARD_FLOOR_POINTS",
45
+ "COARSE_MIN_POINTS",
46
+ "RECOMMENDED_MIN_POINTS",
47
+ "DampingEstimate",
48
+ "acf_curve",
49
+ "acf_efold",
50
+ "check_data_length",
51
+ "dcor",
52
+ "dcor_efold",
53
+ "efold_from_curve",
54
+ "measure",
55
+ "recovery_tau",
56
+ "ringdown_conditional",
57
+ "ringdown_envelope",
58
+ "phase_surrogate_taus",
59
+ "shuffle_null_ringdown",
60
+ "__version__",
61
+ ]
@@ -0,0 +1,289 @@
1
+ """Core estimators: ACF e-fold, distance-correlation e-fold, recovery,
2
+ convergence check, and the top-level ``measure`` entry point."""
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from typing import Dict, List, Optional, Sequence
7
+
8
+ import numpy as np
9
+
10
+ from ._ringdown import ringdown_conditional
11
+
12
+ #: 1/e crossing point for e-fold decay curves.
13
+ EFOLD = float(1.0 / np.e)
14
+
15
+ # Minimum-data reliability tiers (2,800-bootstrap characterization,
16
+ # ±30% hit rate): 20 pts -> 13% (tau underestimated ~2x, hard floor),
17
+ # ~180 pts -> 57% (coarse tier), ~610 pts -> 81.5% (reliable tier).
18
+ HARD_FLOOR_POINTS = 20
19
+ COARSE_MIN_POINTS = 180
20
+ RECOMMENDED_MIN_POINTS = 610
21
+
22
+
23
+ def check_data_length(n: int) -> str:
24
+ """Return the reliability tier for a series of ``n`` samples.
25
+
26
+ ``"insufficient"`` (<20: do not use), ``"coarse"`` (20..179),
27
+ ``"reliable"`` (>=610), ``"marginal"`` (180..609).
28
+ """
29
+ if n < HARD_FLOOR_POINTS:
30
+ return "insufficient"
31
+ if n < COARSE_MIN_POINTS:
32
+ return "coarse"
33
+ if n < RECOMMENDED_MIN_POINTS:
34
+ return "marginal"
35
+ return "reliable"
36
+
37
+
38
+ def dcor(x: Sequence[float], y: Sequence[float]) -> float:
39
+ """Distance correlation between two 1-D samples (biased estimator,
40
+ O(n^2) memory — subsample upstream for long series)."""
41
+ x = np.asarray(x, float)[:, None]
42
+ y = np.asarray(y, float)[:, None]
43
+ a = np.abs(x - x.T)
44
+ b = np.abs(y - y.T)
45
+ A = a - a.mean(0)[None, :] - a.mean(1)[:, None] + a.mean()
46
+ B = b - b.mean(0)[None, :] - b.mean(1)[:, None] + b.mean()
47
+ dcov2 = (A * B).mean()
48
+ dvx = (A * A).mean()
49
+ dvy = (B * B).mean()
50
+ if dvx <= 0 or dvy <= 0:
51
+ return 0.0
52
+ return float(np.sqrt(max(dcov2, 0.0) / np.sqrt(dvx * dvy)))
53
+
54
+
55
+ def efold_from_curve(curve: Sequence[float]) -> float:
56
+ """Lag (float) where a normalized decay curve first crosses 1/e.
57
+
58
+ ``curve[0]`` must be 1.0; NaN entries are tolerated. Linear
59
+ interpolation between bracketing points. Returns NaN when the curve
60
+ never reaches 1/e (e.g. a plateau lifted by a mean offset — check
61
+ your detrending).
62
+ """
63
+ for k in range(1, len(curve)):
64
+ c1 = curve[k]
65
+ if np.isnan(c1):
66
+ continue
67
+ if c1 < EFOLD:
68
+ c0 = curve[k - 1]
69
+ if np.isnan(c0):
70
+ return float(k)
71
+ if c0 == c1:
72
+ return float(k)
73
+ f = (c0 - EFOLD) / (c0 - c1)
74
+ return float(k - 1 + f)
75
+ return float("nan")
76
+
77
+
78
+ def acf_curve(x: Sequence[float], max_lag: int) -> List[float]:
79
+ """Normalized autocorrelation curve, lags 0..max_lag (curve[0] = 1)."""
80
+ x = np.asarray(x, float)
81
+ x = x - x.mean()
82
+ var = float(np.dot(x, x))
83
+ if var <= 0:
84
+ return [1.0] + [float("nan")] * max_lag
85
+ curve = [1.0]
86
+ for k in range(1, max_lag + 1):
87
+ if k >= len(x):
88
+ curve.append(float("nan"))
89
+ continue
90
+ curve.append(float(np.dot(x[:-k], x[k:]) / var))
91
+ return curve
92
+
93
+
94
+ def acf_efold(x: Sequence[float], max_lag: Optional[int] = None) -> float:
95
+ """tau1: ACF e-fold decay time (in samples)."""
96
+ n = len(x)
97
+ max_lag = max_lag or max(10, min(n // 3, 200))
98
+ return efold_from_curve(acf_curve(x, max_lag))
99
+
100
+
101
+ def dcor_efold(
102
+ x: Sequence[float],
103
+ max_lag: Optional[int] = None,
104
+ subsample: int = 1200,
105
+ seed: int = 0,
106
+ ) -> float:
107
+ """tau2: distance-correlation e-fold decay time (in samples).
108
+
109
+ Nonlinear counterpart of the ACF; shift-invariant, useful for
110
+ cross-checking. Pair indices are subsampled beyond ``subsample``
111
+ to keep the O(n^2) kernel tractable.
112
+ """
113
+ x = np.asarray(x, float)
114
+ n = len(x)
115
+ max_lag = max_lag or max(10, min(n // 3, 200))
116
+ rng = np.random.default_rng(seed)
117
+ curve = [1.0]
118
+ for k in range(1, max_lag + 1):
119
+ idx = np.arange(0, n - k)
120
+ if len(idx) < 30:
121
+ curve.append(float("nan"))
122
+ continue
123
+ if len(idx) > subsample:
124
+ idx = rng.choice(idx, subsample, replace=False)
125
+ curve.append(dcor(x[idx], x[idx + k]))
126
+ return efold_from_curve(curve)
127
+
128
+
129
+ def recovery_tau(
130
+ x: Sequence[float],
131
+ drop_mask: Optional[Sequence[bool]] = None,
132
+ threshold: float = 2.0,
133
+ cap: Optional[int] = None,
134
+ ) -> float:
135
+ """tau4 (auxiliary): median time-to-recover after large drops.
136
+
137
+ Right-censoring warning: when the window ends before recovery, the
138
+ capped value is *censoring*, not an estimate. Never treat tau4 alone
139
+ as evidence; use it as a supporting check only.
140
+ """
141
+ x = np.asarray(x, float)
142
+ if drop_mask is None:
143
+ dx = np.diff(x, prepend=x[0])
144
+ sig = float(np.std(dx[1:])) if len(x) > 2 else 0.0
145
+ drop_mask = dx < -threshold * sig
146
+ drop_mask[0] = False
147
+ drop_mask = np.asarray(drop_mask, bool)
148
+ cap = cap or max(10, len(x) // 20)
149
+ recs = []
150
+ for t in np.where(drop_mask)[0]:
151
+ if t < 1 or t + cap >= len(x):
152
+ continue
153
+ lvl = x[t - 1]
154
+ r = cap
155
+ for k in range(1, cap + 1):
156
+ if x[t + k] >= lvl:
157
+ r = k
158
+ break
159
+ recs.append(r)
160
+ return float(np.median(recs)) if recs else float("nan")
161
+
162
+
163
+ @dataclass
164
+ class DampingEstimate:
165
+ """Result of :func:`measure`.
166
+
167
+ ``tau`` is the converged estimate in *time units* (samples x dt);
168
+ ``gamma = 1/tau``. ``converged`` is True when at least
169
+ ``min_converging`` estimators fall within ±30% of the median —
170
+ convergence is an identity check ("this constant is really there"),
171
+ not a goodness-of-fit score.
172
+ """
173
+
174
+ tau: float
175
+ gamma: float
176
+ median_tau: float
177
+ taus: Dict[str, float]
178
+ converged: bool
179
+ within_30pct: int
180
+ n_methods: int
181
+ n_samples: int
182
+ data_tier: str
183
+ dt: float
184
+ warnings: List[str] = field(default_factory=list)
185
+
186
+ def as_dict(self) -> Dict[str, object]:
187
+ return {
188
+ "tau": self.tau,
189
+ "gamma": self.gamma,
190
+ "median_tau": self.median_tau,
191
+ "taus": self.taus,
192
+ "converged": self.converged,
193
+ "within_30pct": f"{self.within_30pct}/{self.n_methods}",
194
+ "n_samples": self.n_samples,
195
+ "data_tier": self.data_tier,
196
+ "dt": self.dt,
197
+ "warnings": self.warnings,
198
+ }
199
+
200
+
201
+ def measure(
202
+ x: Sequence[float],
203
+ dt: float = 1.0,
204
+ max_lag: Optional[int] = None,
205
+ pulse_threshold: float = 2.0,
206
+ min_converging: int = 3,
207
+ dcor_subsample: int = 1200,
208
+ seed: int = 0,
209
+ include_recovery: bool = True,
210
+ ) -> DampingEstimate:
211
+ """Estimate the intrinsic damping time tau of a scalar time series.
212
+
213
+ Runs three independent estimators — tau1 ACF e-fold, tau2 dCor
214
+ e-fold, tau3 impulse-conditioned ring-down — plus the auxiliary tau4
215
+ post-drop recovery. Convergence: >= ``min_converging`` methods within
216
+ ±30% of the median => the constant is considered established.
217
+
218
+ Parameters
219
+ ----------
220
+ x : scalar series (assumed stationary window, effectively linear
221
+ relaxation). Detrend before calling — fitting on raw data with a
222
+ mean offset lifts the ACF plateau so the curve never reaches 1/e.
223
+ dt : sample spacing; tau and gamma are returned in these time units.
224
+ """
225
+ x = np.asarray(x, float)
226
+ n = len(x)
227
+ warnings: List[str] = []
228
+ tier = check_data_length(n)
229
+ if tier == "insufficient":
230
+ warnings.append(
231
+ f"n={n} < {HARD_FLOOR_POINTS}: below the hard floor — tau is "
232
+ "systematically underestimated (~2x on short windows). Do not use."
233
+ )
234
+ elif tier == "coarse":
235
+ warnings.append(
236
+ f"n={n}: coarse tier (~57% hit rate at 180 pts). Treat as "
237
+ "indicative only; >=610 pts recommended for reliable tier."
238
+ )
239
+ elif tier == "marginal":
240
+ warnings.append(f"n={n}: between coarse and reliable tiers (~610 pts).")
241
+
242
+ tau1 = acf_efold(x, max_lag=max_lag)
243
+ tau2 = dcor_efold(x, max_lag=max_lag, subsample=dcor_subsample, seed=seed)
244
+
245
+ dx = np.diff(x, prepend=x[0])
246
+ sig = float(np.std(dx[1:])) if n > 2 else 0.0
247
+ pulse = np.abs(dx) > pulse_threshold * sig
248
+ pulse[0] = False
249
+ tau3 = ringdown_conditional(x, pulse_mask=pulse, max_lag=max_lag)
250
+
251
+ taus = {"tau1_acf": tau1, "tau2_dcor": tau2, "tau3_ringdown": tau3}
252
+ if include_recovery:
253
+ taus["tau4_recovery"] = recovery_tau(x, drop_mask=dx < -pulse_threshold * sig)
254
+
255
+ valid = {k: v for k, v in taus.items() if not np.isnan(v)}
256
+ if not valid:
257
+ return DampingEstimate(
258
+ tau=float("nan"), gamma=float("nan"), median_tau=float("nan"),
259
+ taus=taus, converged=False, within_30pct=0,
260
+ n_methods=len(taus), n_samples=n, data_tier=tier, dt=dt,
261
+ warnings=warnings + ["no estimator produced a finite tau"],
262
+ )
263
+
264
+ # tau4 is auxiliary (right-censoring prone): convergence is judged
265
+ # on tau1/tau2/tau3, matching the validated IDV protocol.
266
+ primary = {k: v for k, v in valid.items() if k != "tau4_recovery"} or valid
267
+ med = float(np.median(list(primary.values())))
268
+ within = sum(1 for v in primary.values() if abs(v - med) <= 0.3 * med)
269
+ converged = within >= min_converging
270
+ if not converged:
271
+ warnings.append(
272
+ f"only {within}/{len(primary)} primary estimators within ±30% of "
273
+ f"median {med:.3g}: individual damping NOT established (either the "
274
+ "window is not a stationary relaxation regime, or data too short)."
275
+ )
276
+ tau = med * dt
277
+ return DampingEstimate(
278
+ tau=tau,
279
+ gamma=(1.0 / tau) if tau > 0 else float("nan"),
280
+ median_tau=med,
281
+ taus={k: (v * dt if not np.isnan(v) else float("nan")) for k, v in taus.items()},
282
+ converged=converged,
283
+ within_30pct=within,
284
+ n_methods=len(primary),
285
+ n_samples=n,
286
+ data_tier=tier,
287
+ dt=dt,
288
+ warnings=warnings,
289
+ )
@@ -0,0 +1,66 @@
1
+ """Null controls.
2
+
3
+ A damping estimate is only physical if it collapses when temporal
4
+ structure is destroyed. Two standard controls:
5
+
6
+ * :func:`shuffle_null_ringdown` — shuffle within blocks (e.g. within
7
+ each year/season) to destroy temporal structure while preserving the
8
+ marginal distribution; the ring-down tau should collapse.
9
+ * :func:`phase_surrogate_taus` — phase-randomized surrogates preserve
10
+ the power spectrum; ACF tau should survive (same spectrum) while the
11
+ point is to check estimator stability, not to falsify physics.
12
+
13
+ If the null does NOT collapse, you are reading a mathematical necessity
14
+ (e.g. a monotone trend or a mean offset), not physics — invalidate.
15
+ """
16
+ from __future__ import annotations
17
+
18
+ from typing import Optional, Sequence
19
+
20
+ import numpy as np
21
+
22
+ from ._core import acf_efold
23
+ from ._ringdown import ringdown_conditional
24
+
25
+
26
+ def shuffle_null_ringdown(
27
+ x: Sequence[float],
28
+ blocks: Optional[Sequence[int]] = None,
29
+ threshold: float = 2.0,
30
+ seed: int = 0,
31
+ ) -> float:
32
+ """Ring-down tau after within-block shuffling (NaN if no events).
33
+
34
+ ``blocks``: label per sample (e.g. year numbers); shuffling happens
35
+ within each block. Default: one block (whole series).
36
+ """
37
+ x = np.asarray(x, float)
38
+ rng = np.random.default_rng(seed)
39
+ xs = x.copy()
40
+ blocks = np.asarray(blocks) if blocks is not None else np.zeros(len(x), int)
41
+ for b in np.unique(blocks):
42
+ m = np.where(blocks == b)[0]
43
+ xs[m] = rng.permutation(xs[m])
44
+ dx = np.diff(xs, prepend=xs[0])
45
+ sig = float(np.std(dx[1:])) if len(x) > 2 else 0.0
46
+ pulse = np.abs(dx) > threshold * sig
47
+ pulse[0] = False
48
+ return ringdown_conditional(xs, pulse_mask=pulse)
49
+
50
+
51
+ def phase_surrogate_taus(
52
+ x: Sequence[float],
53
+ n: int = 10,
54
+ seed: int = 0,
55
+ ) -> np.ndarray:
56
+ """ACF tau of ``n`` phase-randomized surrogates (spectrum-preserving)."""
57
+ x = np.asarray(x, float)
58
+ rng = np.random.default_rng(seed)
59
+ out = []
60
+ for _ in range(n):
61
+ X = np.fft.rfft(x - x.mean())
62
+ ph = rng.uniform(0, 2 * np.pi, len(X))
63
+ ph[0] = 0
64
+ xs = np.fft.irfft(np.abs(X) * np.exp(1j * ph), n=len(x))
65
+ out.append(acf_efold(xs))
66
+ return np.asarray(out)
@@ -0,0 +1,138 @@
1
+ """Ring-down estimators.
2
+
3
+ Two calibers, deliberately kept separate:
4
+
5
+ * :func:`ringdown_conditional` — impulse-conditioned decay R(k), the
6
+ estimator validated in the polar-vortex IDV case (tau3).
7
+ * :func:`ringdown_envelope` — analytic-envelope decay on band-passed
8
+ oscillatory signals (bearing / vibration style). This is the
9
+ CORRECTED caliber: Hilbert analytic envelope + normalized MAD event
10
+ threshold ``median|env - median(env)| * 1.4826``.
11
+
12
+ Known failure modes these implementations are built against:
13
+
14
+ * using |band-passed| as the "envelope" quantizes tau at the oscillation
15
+ half-period (measures ringing, not damping);
16
+ * using ``median(env) * 1.4826`` as the MAD is wrong — the threshold
17
+ lands near ~5 sigma under a Rayleigh envelope and almost nothing
18
+ crosses it.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ from typing import List, Optional, Sequence, Tuple
23
+
24
+ import numpy as np
25
+ from scipy import signal as sp_signal
26
+
27
+
28
+ def ringdown_conditional(
29
+ x: Sequence[float],
30
+ pulse_mask: Optional[Sequence[bool]] = None,
31
+ threshold: float = 2.0,
32
+ max_lag: Optional[int] = None,
33
+ min_events: int = 10,
34
+ ) -> float:
35
+ """tau3: impulse-conditioned ring-down e-fold (in samples).
36
+
37
+ R(k) = E[x(t)x(t+k) | pulse] / E[x(t)^2 | pulse]: decay of the
38
+ conditional response after large-impulse days. NaN when fewer than
39
+ ``min_events`` usable pulses.
40
+ """
41
+ x = np.asarray(x, float)
42
+ if pulse_mask is None:
43
+ dx = np.diff(x, prepend=x[0])
44
+ sig = float(np.std(dx[1:])) if len(x) > 2 else 0.0
45
+ pulse_mask = np.abs(dx) > threshold * sig
46
+ pulse_mask[0] = False
47
+ pulse_mask = np.asarray(pulse_mask, bool)
48
+ max_lag = max_lag or max(10, min(len(x) // 5, 100))
49
+ ps = np.where(pulse_mask)[0]
50
+ if len(ps) < min_events:
51
+ return float("nan")
52
+ base = float(np.mean(x[pulse_mask] ** 2))
53
+ if base <= 0:
54
+ return float("nan")
55
+ curve = [1.0]
56
+ for k in range(1, max_lag + 1):
57
+ pk = ps[ps + k < len(x)]
58
+ if len(pk) < min_events:
59
+ curve.append(float("nan"))
60
+ continue
61
+ curve.append(float(np.mean(x[pk] * x[pk + k]) / base))
62
+ from ._core import efold_from_curve
63
+
64
+ return efold_from_curve(curve)
65
+
66
+
67
+ def _normalized_mad(env: np.ndarray) -> float:
68
+ """CORRECT MAD: median|env - median(env)| * 1.4826."""
69
+ med = float(np.median(env))
70
+ return float(np.median(np.abs(env - med)) * 1.4826)
71
+
72
+
73
+ def ringdown_envelope(
74
+ x: Sequence[float],
75
+ fs: float = 1.0,
76
+ band: Optional[Tuple[float, float]] = None,
77
+ mad_k: float = 1.0,
78
+ min_events: int = 5,
79
+ ) -> float:
80
+ """Analytic-envelope ring-down decay time (in time units = 1/fs).
81
+
82
+ Band-pass (optional), take the Hilbert analytic envelope, smooth it,
83
+ threshold events at ``mad_k * normalized_MAD``, then fit the
84
+ exponential decay of each event envelope tail (peak → thr/e); the
85
+ median event tau is returned. NaN when fewer than ``min_events`` events.
86
+
87
+ ``band``: (low, high) in Hz, relative to fs. Default = no band-pass
88
+ (use when the series is already band-limited).
89
+
90
+ The one caliber rule: envelope = |hilbert(bandpassed)|. Never
91
+ |bandpassed| — that quantizes tau to the oscillation half-period.
92
+ """
93
+ x = np.asarray(x, float)
94
+ if len(x) < 20:
95
+ return float("nan")
96
+ y = x - x.mean()
97
+ if band is not None:
98
+ lo, hi = band
99
+ nyq = fs / 2.0
100
+ b, a = sp_signal.butter(2, [lo / nyq, hi / nyq], btype="band")
101
+ y = sp_signal.filtfilt(b, a, y)
102
+ env = np.abs(sp_signal.hilbert(y))
103
+ # light smoothing of the envelope (3-point moving average)
104
+ if len(env) >= 3:
105
+ env = np.convolve(env, np.ones(3) / 3.0, mode="same")
106
+
107
+ # trim Hilbert/convolution edge artifacts
108
+ edge = min(5, len(env) // 10)
109
+ env = env[edge:len(env) - edge] if edge > 0 else env
110
+
111
+ thr = mad_k * _normalized_mad(env)
112
+ if thr <= 0:
113
+ return float("nan")
114
+
115
+ # event onsets: upward crossings of the threshold
116
+ above = env > thr
117
+ onsets = np.where(np.diff(above.astype(int)) == 1)[0] + 1
118
+ taus: List[float] = []
119
+ for i, t0 in enumerate(onsets):
120
+ # tail: from local peak to thr/e, cut before the next event rises
121
+ seg = env[t0:]
122
+ pk_rel = int(np.argmax(seg[:min(10, len(seg))]))
123
+ tail = seg[pk_rel:]
124
+ stop = np.where(tail <= thr / np.e)[0]
125
+ end = int(stop[0]) if len(stop) else len(tail)
126
+ if i + 1 < len(onsets):
127
+ end = min(end, int(onsets[i + 1] - t0 - pk_rel))
128
+ if end < 4:
129
+ continue
130
+ tail = tail[:end]
131
+ yy = np.log(np.maximum(tail, 1e-300))
132
+ tt = np.arange(len(tail), dtype=float)
133
+ slope = np.polyfit(tt, yy, 1)[0]
134
+ if slope < 0:
135
+ taus.append(-1.0 / slope)
136
+ if len(taus) < min_events:
137
+ return float("nan")
138
+ return float(np.median(taus))
File without changes
@@ -0,0 +1,119 @@
1
+ Metadata-Version: 2.4
2
+ Name: dampmeter
3
+ Version: 1.0.0
4
+ Summary: IDV damping caliper: measure a system's intrinsic relaxation time tau (gamma = 1/tau) from a single scalar time series — four-test convergence + shuffle null, KB-RAM / millisecond class, built for edge devices
5
+ Author: Ma Ka Po
6
+ Author-email: "tygtDc, Deep Research" <drtygtdc@gmail.com>
7
+ License: CC BY 4.0
8
+ Keywords: damping,relaxation time,time series,nonlinear dynamics,autocorrelation,distance correlation,ring-down,edge computing,structural health monitoring,attractor
9
+ Classifier: Development Status :: 5 - Production/Stable
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: License :: Other/Proprietary License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Topic :: Scientific/Engineering :: Physics
18
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
19
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: numpy>=1.24
24
+ Requires-Dist: scipy>=1.10
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7; extra == "dev"
27
+ Dynamic: license-file
28
+
29
+ # dampmeter — IDV individual damping caliper
30
+
31
+ **Measure a system's intrinsic relaxation time τ (γ = 1/τ) from a single scalar time series.**
32
+ Four independent estimators, convergence-as-identity-check, shuffle-null control.
33
+ KB-RAM / millisecond class — built for edge devices.
34
+
35
+ ```python
36
+ import dampmeter as dm
37
+
38
+ est = dm.measure(x, dt=1.0) # x = one scalar series, stationary window
39
+ est.tau # damping time constant, in units of dt
40
+ est.gamma # 1/tau
41
+ est.converged # True when >=3 estimators agree within ±30% of the median
42
+ ```
43
+
44
+ ## What it measures (and what it does not)
45
+
46
+ | | |
47
+ |---|---|
48
+ | ✅ **Effective damping time τ** | how fast perturbations decay inside a stable regime (effective linear relaxation) |
49
+ | ✅ **Stability of τ** | convergence across independent estimators + a shuffle null — "this constant is really there", not "the fit looks good" |
50
+ | ❌ **Mechanism** | γ is *effective* only; decomposing it (radiative vs wave drag vs friction…) needs budget methods |
51
+ | ❌ **Potential-well stiffness** | stiffness is curvature (ω₀²), a different physical quantity — this package measures dissipation, not stiffness |
52
+ | ❌ **Sign of degradation** | "damage → damping" has no universal sign: defect-size axis (τ↑) and wear/life axis (τ↓) can go opposite ways — always specify the axis before interpreting trends |
53
+
54
+ ## Estimators
55
+
56
+ | Method | What it does |
57
+ |---|---|
58
+ | `tau1_acf` | autocorrelation e-fold decay |
59
+ | `tau2_dcor` | distance-correlation e-fold (nonlinear, shift-invariant) |
60
+ | `tau3_ringdown` | impulse-conditioned ring-down decay R(k) |
61
+ | `tau4_recovery` | post-drop recovery time (auxiliary; right-censoring prone — never evidence alone) |
62
+
63
+ Convergence rule: at least 3 of the primary methods within ±30% of the median ⇒ individual damping established. Two ring-down calibers are provided and deliberately kept separate:
64
+
65
+ - `ringdown_conditional` — impulse-conditioned decay (the validated IDV estimator);
66
+ - `ringdown_envelope` — analytic-envelope decay for band-passed oscillatory signals, using the **Hilbert analytic envelope** with the normalized MAD event threshold `median|env − median(env)| × 1.4826`.
67
+ Known traps these are built against: `|band-passed|` as the "envelope" quantizes τ to the oscillation half-period; `median(env) × 1.4826` is the wrong MAD (threshold lands near ~5σ, almost nothing crosses it).
68
+
69
+ ## Minimum data (2,800-bootstrap characterization, ±30% hit rate)
70
+
71
+ | Samples | Hit rate | Verdict |
72
+ |---|---|---|
73
+ | 20 | 13% (τ underestimated ~2×) | ❌ hard floor — do not use |
74
+ | ~180 | 57% | ⚠️ coarse tier |
75
+ | **~610** | **81.5%** | ✅ reliable tier |
76
+ | ~1,220 | 97% | ✅ stable |
77
+
78
+ The impulse ring-down method needs more: ≥40 pulses ≈ 1,500 samples for 65%.
79
+ Compute: single core seconds (2,800 bootstraps), RAM KB-class, per-test milliseconds — 6–9 orders of magnitude cheaper than reanalysis-budget approaches.
80
+
81
+ ## Null control (do not skip)
82
+
83
+ ```python
84
+ tau_null = dm.shuffle_null_ringdown(x, blocks=years) # shuffle within blocks
85
+ ```
86
+
87
+ If the ring-down τ does **not** collapse after temporal structure is destroyed, you are reading a mathematical necessity (trend / mean offset), not physics — invalidate the estimate.
88
+
89
+ ## Pitfalls
90
+
91
+ - **Detrend first** (fit the trend on the anomaly, not the raw series). A mean offset lifts the ACF plateau so the curve never reaches 1/e (NaN) — the dCor estimate stays shift-invariant and can help locate the problem.
92
+ - **Stationary window + effective linear relaxation** are the working assumptions.
93
+ - **Short-lived systems** (e.g. ~10-day storms) cannot pass the 610-sample floor.
94
+ - **Do not transplant thresholds across domains** (geometric cutoffs, event quantiles): re-derive per domain with sensitivity checks, and calibrate on a ground-truth domain first.
95
+
96
+ ## Validation status (honest)
97
+
98
+ - τ convergence (3 methods: 11.28 / 10.81 / 13.32 → τ ≈ 12.3 days) and shuffle-null collapse (τ → 0.9) have been demonstrated on **one physical system** (stratospheric polar vortex, 2,867 daily samples). Ring-down caliber applications exist on two more domains (bearing vibration, ECG), single-caliber only.
99
+ - Cross-domain τ convergence replication is pending — treat new domains as unvalidated until you run convergence + null there.
100
+
101
+ ## Install
102
+
103
+ ```bash
104
+ pip install dampmeter
105
+ ```
106
+
107
+ Pure numpy + scipy. Python ≥ 3.9.
108
+
109
+ ## References
110
+
111
+ Part of the Ô-HAT dual-operator measurement primitive (IDV caliper + T blind-state gatekeeper). Method details, usage boundaries and the engineering interface table: `project/ohat_framework/note-dual-operator-idv-t.md` (framework v3.7, §3.12).
112
+
113
+ ## Authors
114
+
115
+ tygtDc, Deep Research (correspondence: drtygtdc@gmail.com) · Ma Ka Po
116
+
117
+ ## License
118
+
119
+ CC BY 4.0 — free to use, adapt and commercialize with attribution.
@@ -0,0 +1,14 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/dampmeter/__init__.py
5
+ src/dampmeter/_core.py
6
+ src/dampmeter/_null.py
7
+ src/dampmeter/_ringdown.py
8
+ src/dampmeter/py.typed
9
+ src/dampmeter.egg-info/PKG-INFO
10
+ src/dampmeter.egg-info/SOURCES.txt
11
+ src/dampmeter.egg-info/dependency_links.txt
12
+ src/dampmeter.egg-info/requires.txt
13
+ src/dampmeter.egg-info/top_level.txt
14
+ tests/test_core.py
@@ -0,0 +1,5 @@
1
+ numpy>=1.24
2
+ scipy>=1.10
3
+
4
+ [dev]
5
+ pytest>=7
@@ -0,0 +1 @@
1
+ dampmeter
@@ -0,0 +1,98 @@
1
+ """dampmeter smoke tests on synthetic data with known ground truth."""
2
+ import numpy as np
3
+ import pytest
4
+
5
+ import dampmeter as dm
6
+
7
+
8
+ def ou_process(n=610, tau=12.3, dt=1.0, seed=1):
9
+ """Discrete OU: x[t+1] = x[t]*exp(-dt/tau) + noise (variance-matched)."""
10
+ rng = np.random.default_rng(seed)
11
+ a = np.exp(-dt / tau)
12
+ q = 1.0 - a * a
13
+ x = np.zeros(n)
14
+ for t in range(1, n):
15
+ x[t] = a * x[t - 1] + rng.normal(0.0, np.sqrt(q))
16
+ return x
17
+
18
+
19
+ def test_dcor_self_is_one():
20
+ rng = np.random.default_rng(0)
21
+ x = rng.normal(size=200)
22
+ assert dm.dcor(x, x) == pytest.approx(1.0, abs=1e-6)
23
+
24
+
25
+ def test_efold_monotone_curve():
26
+ curve = [1.0, 0.8, 0.5, 0.3, 0.2]
27
+ lag = dm.efold_from_curve(curve)
28
+ assert 1.0 < lag < 3.0
29
+ assert np.isnan(dm.efold_from_curve([1.0, 0.9, 0.85]))
30
+
31
+
32
+ def test_measure_recovers_ou_tau():
33
+ x = ou_process(n=2000, tau=12.3, seed=1)
34
+ est = dm.measure(x, dt=1.0, seed=1)
35
+ # within ±30% of ground truth 12.3
36
+ assert not np.isnan(est.tau)
37
+ assert abs(est.tau - 12.3) <= 0.3 * 12.3
38
+ assert est.converged
39
+ assert est.gamma == pytest.approx(1.0 / est.tau)
40
+
41
+
42
+ def test_measure_short_series_warns():
43
+ x = ou_process(n=15, tau=5.0, seed=2)
44
+ est = dm.measure(x, dt=1.0, seed=2)
45
+ assert est.data_tier == "insufficient"
46
+ assert any("Do not use" in w for w in est.warnings)
47
+
48
+
49
+ def test_tier_boundaries():
50
+ assert dm.check_data_length(15) == "insufficient"
51
+ assert dm.check_data_length(100) == "coarse"
52
+ assert dm.check_data_length(300) == "marginal"
53
+ assert dm.check_data_length(610) == "reliable"
54
+
55
+
56
+ def test_shuffle_null_collapses():
57
+ rng = np.random.default_rng(3)
58
+ x = ou_process(n=2000, tau=20.0, seed=3)
59
+ tau_real = dm.ringdown_conditional(x)
60
+ tau_null = dm.shuffle_null_ringdown(x, blocks=np.arange(2000) // 100, seed=3)
61
+ assert np.isnan(tau_real) or np.isnan(tau_null) or tau_null < tau_real
62
+ _ = rng # silence lint
63
+
64
+
65
+ def test_envelope_tau_on_damped_oscillation():
66
+ # repeated ring-down bursts: exp(-t/15) * cos(2*pi*0.2*t) every 300 pts
67
+ rng = np.random.default_rng(4)
68
+ t = np.arange(0, 1800)
69
+ x = 0.01 * rng.normal(size=len(t))
70
+ for t0 in range(0, 1800, 300):
71
+ dt_ = t - t0
72
+ burst = np.where(dt_ >= 0, np.exp(-np.maximum(dt_, 0) / 15.0)
73
+ * np.cos(2 * np.pi * 0.2 * np.maximum(dt_, 0)), 0.0)
74
+ x += burst
75
+ tau = dm.ringdown_envelope(x, fs=1.0, band=(0.15, 0.25))
76
+ assert not np.isnan(tau)
77
+ assert abs(tau - 15.0) <= 0.5 * 15.0
78
+
79
+
80
+ def test_envelope_mad_formula():
81
+ env = np.abs(np.random.default_rng(5).rayleigh(size=5000))
82
+ med = np.median(env)
83
+ wrong = med * 1.4826
84
+ right = np.median(np.abs(env - med)) * 1.4826
85
+ # the documented failure mode: median(env)*1.4826 is far too high
86
+ assert wrong > right * 1.5
87
+
88
+
89
+ def test_recovery_tau_positive():
90
+ x = ou_process(n=1000, tau=10.0, seed=6)
91
+ r = dm.recovery_tau(x)
92
+ assert np.isnan(r) or r > 0
93
+
94
+
95
+ def test_as_dict_roundtrip():
96
+ est = dm.measure(ou_process(n=610, tau=12.3, seed=7), seed=7)
97
+ d = est.as_dict()
98
+ assert set(d) >= {"tau", "gamma", "taus", "converged", "warnings"}