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.
- dampmeter-1.0.0/LICENSE +25 -0
- dampmeter-1.0.0/PKG-INFO +119 -0
- dampmeter-1.0.0/README.md +91 -0
- dampmeter-1.0.0/pyproject.toml +46 -0
- dampmeter-1.0.0/setup.cfg +4 -0
- dampmeter-1.0.0/src/dampmeter/__init__.py +61 -0
- dampmeter-1.0.0/src/dampmeter/_core.py +289 -0
- dampmeter-1.0.0/src/dampmeter/_null.py +66 -0
- dampmeter-1.0.0/src/dampmeter/_ringdown.py +138 -0
- dampmeter-1.0.0/src/dampmeter/py.typed +0 -0
- dampmeter-1.0.0/src/dampmeter.egg-info/PKG-INFO +119 -0
- dampmeter-1.0.0/src/dampmeter.egg-info/SOURCES.txt +14 -0
- dampmeter-1.0.0/src/dampmeter.egg-info/dependency_links.txt +1 -0
- dampmeter-1.0.0/src/dampmeter.egg-info/requires.txt +5 -0
- dampmeter-1.0.0/src/dampmeter.egg-info/top_level.txt +1 -0
- dampmeter-1.0.0/tests/test_core.py +98 -0
dampmeter-1.0.0/LICENSE
ADDED
|
@@ -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
|
dampmeter-1.0.0/PKG-INFO
ADDED
|
@@ -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,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 @@
|
|
|
1
|
+
|
|
@@ -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"}
|