tc-cwi 0.1.0__tar.gz

tc_cwi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zensor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tc_cwi-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: tc-cwi
+Version: 0.1.0
+Summary: Python toolbox to apply EOC compensation algorithms to ultrasonic testing data.
+Keywords: coda wave interferometry,structural health monitoring,temperature compensation,time-stretching,ultrasonic
+Author: Arnaud Deraemaeker (ULB), Damiano Gianotti (Zensor), Jasmien Hassanin (IZFP), Jitendra Kumar Sharma (ULB), Luigi Trezza (Airbus)
+Author-email: Arnaud Deraemaeker (ULB) <Arnaud.Deraemaeker@ulb.be>, Damiano Gianotti (Zensor) <damiano.gianotti@zensor.be>, Jitendra Kumar Sharma (ULB) <jitendra.kumar.sharma@ulb.be>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Dist: numpy
+Requires-Dist: scipy
+Maintainer: Zensor
+Maintainer-email: Zensor <support@zensor.be>
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/Zensor-BE/tc-cwi
+Project-URL: Issues, https://github.com/Zensor-BE/tc-cwi/issues
+Description-Content-Type: text/markdown
+
+# `tc-cwi`
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Build System](https://img.shields.io/badge/build-uv__build-blueviolet)](https://github.com/astral-sh/uv)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Zensor-BE/tc-cwi/blob/main/LICENSE)
+
+Lightweight Python toolbox for **Environmental and Operational Condition (EoC) compensation** in ultrasonic Structural Health Monitoring (SHM), using **Coda Wave Interferometry (CWI)** and the **Time-Stretching method**.
+
+Temperature variations change the apparent wave velocity of ultrasonic guided waves, which can mask structural damage. `tc-cwi` estimates the stretch factor (`eps`) and/or time shift (`dt`) that best realign a measured signal with a reference, and reports the remaining decorrelation.
+
+Developed as part of WP3, Deliverable D3.3.
+
+---
+
+## Installation
+
+Requirements: **Python ≥ 3.11** (dependencies: `numpy`, `scipy`)
+
+```bash
+pip install tc-cwi
+```
+
+---
+
+## Quickstart
+
+```python
+import numpy as np
+from tc_cwi import tc_cwi
+
+t = np.linspace(0, 1e-3, 1000)
+reference = np.sin(2 * np.pi * 50e3 * t)
+current = np.sin(2 * np.pi * 50e3 * t * (1 + 1e-4))  # slightly stretched
+
+# Correlation coefficient without compensation (one value per signal)
+baseline = tc_cwi("getccns", reference, current)
+print(f"Baseline CC: {baseline.CC[0]:.4f}")
+
+# Optimal stretch factor (Nelder-Mead from eps = 0) and remaining decorrelation
+result = tc_cwi("findeps", reference, current, t, 0.0, 2)
+print(f"eps: {result.eps:.6e}, decorrelation after stretching: {result.DC:.2e}")
+```
+
+Several signals can be processed at once by passing a 2D array with **one signal per column** (`n_samples × n_signals`):
+
+```python
+signals = np.column_stack([current, current, current])
+batch = tc_cwi("findeps", reference, signals, t, (-1e-2, 1e-2))  # bounded search
+print(batch.EPSf, batch.DCsf)
+```
+
+---
+
+## API
+
+The package exposes two layers.
+
+### MATLAB-compatible dispatch: `tc_cwi(cmd, *args, **kwargs)`
+
+Mirrors the original MATLAB toolbox. Results are returned as a `Struct` (`types.SimpleNamespace`), so fields are accessed MATLAB-style with `out.field`.
+
+| Command | Arguments | Output fields (single signal / multiple signals) |
+|---|---|---|
+| `getccns` | `y0, y1, ind=None` | `CC`, `DC` |
+| `getccs` | `y0, y1, t, eps, ind=None` | `CC`, `DC` |
+| `getccdt` | `y0, y1, t, dt, ind=None` | `CC`, `DC` |
+| `getccepsdt` | `y0, y1, t, eps, dt, ind=None` | `CC`, `DC` |
+| `getdcs` / `getdcdt` / `getdcepsdt` | same as `getcc*` | `DC` array (returned directly) |
+| `findeps` | `y1, y2, t, e0, method=1, ind=None` | `eps, DC, y, y0` / `EPSf, DCsf, ysf, y0` |
+| `finddt` | `y1, y2, t, dt0, method=1, ind=None` | `dt, DC, y, y0` / `DTf, DCdtf, ydtf, y0` |
+| `findepsdt` | `y1, y2, t, e0, dt0, method=2, ind=None` | `eps, dt, DC, y, y0` / `EPSf, DTf, DCsdtf, ysdtf, y0` |
+| `findeps -ma` | `y1, y2, t, e0, method=1, ind=None, ma=5` | multiple signals only: `EPSma, DCma, ysma, y0, yma` |
+| `stretch` | `y, t, eps` | stretched signal |
+| `shift` | `y, t, dt, method="interp"` | shifted signal (`"point"`, `"interp"` or `"fft"`) |
+| `stretchshift` | `y, t, eps, dt` | shifted, then stretched signal |
+
+Conventions:
+
+- **`CC`** is the absolute Pearson correlation coefficient, **`DC = 1 - CC`** the decorrelation.
+- **`ind`** restricts the correlation to a window (index array or slice). The stretch/shift is always applied to the full signal.
+- **`method`** selects the optimizer:
+  - `1`: bounded scalar search, the start value is an interval `(lower, upper)`.
+  - `2`: Nelder-Mead, the start value is a starting point. `findepsdt` only supports this method.
+
+  When processing several signals, each fit is seeded with the result of the previous one.
+- **`eps > 0`** compresses the wave (`t → t·(1+eps)`), **`dt > 0`** moves it forward (`t → t−dt`).
+- **`findeps -ma`** compares each signal against the mean of the last `ma` compensated signals instead of a fixed reference. `ma` is either a window size, or the `yma` returned by a previous call to continue the same window.
+
+### Core functions
+
+For direct use in Python code, without the MATLAB-style dispatch:
+
+| Function | Description |
+|---|---|
+| `correlation_coefficient(y0, y1)` | Absolute correlation coefficient between two signals |
+| `stretch(y, t, eps)` | Stretch a signal (not-a-knot cubic spline, zero outside `t`) |
+| `shift(y, t, dt, method="interp")` | Shift a signal by `dt` |
+| `stretchshift(y, t, eps, dt)` | Shift, then stretch a signal |
+| `find_optimum(y0, y, t, process, x0, method=1, ind=None, xatol=1e-8)` | Parameters of `process(y, t, *x)` minimizing the decorrelation with `y0`; returns `(x, decorrelation)` |
+| `MovingAverageReference(n, y_init=None)` | Rolling window of the last `n` signals; `.reference` is their mean, `.update(y)` adds a signal |
+
+```python
+from tc_cwi import find_optimum, stretch
+
+x, decorrelation = find_optimum(reference, current, t, stretch, (-1e-2, 1e-2))
+```
+
+---
+
+## Development
+
+This project uses [`uv`](https://github.com/astral-sh/uv) with the `uv_build` backend:
+
+```bash
+git clone https://github.com/Zensor-BE/tc-cwi.git
+cd tc-cwi
+uv sync
+```
+
+```text
+├── src/tc_cwi/
+│   ├── __init__.py      # Public API
+│   ├── core.py          # Stretching, shifting and optimization
+│   └── matlab.py        # MATLAB-compatible tc_cwi() dispatch
+├── tests/
+│   ├── test_core.py     # Core functions
+│   ├── test_matlab.py   # Every tc_cwi command: fields and error paths
+│   └── test_package.py  # Public API
+└── pyproject.toml
+```
+
+Tests, coverage and linting:
+
+```bash
+uv run pytest
+uv run pytest --cov   # statements + branches, with the missing lines
+uv run ruff check .
+```
+
+Releasing to PyPI: bump `version` in `pyproject.toml`, then push a matching tag. The [publish workflow](https://github.com/Zensor-BE/tc-cwi/blob/main/.github/workflows/publish.yml) lints, builds, tests the built distributions and publishes them.
+
+```bash
+git tag -a v0.1.0 -m v0.1.0
+git push origin v0.1.0
+```
+
+---
+
+## License
+
+[MIT](https://github.com/Zensor-BE/tc-cwi/blob/main/LICENSE)

tc_cwi-0.1.0/README.md

@@ -0,0 +1,151 @@
+# `tc-cwi`
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Build System](https://img.shields.io/badge/build-uv__build-blueviolet)](https://github.com/astral-sh/uv)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Zensor-BE/tc-cwi/blob/main/LICENSE)
+
+Lightweight Python toolbox for **Environmental and Operational Condition (EoC) compensation** in ultrasonic Structural Health Monitoring (SHM), using **Coda Wave Interferometry (CWI)** and the **Time-Stretching method**.
+
+Temperature variations change the apparent wave velocity of ultrasonic guided waves, which can mask structural damage. `tc-cwi` estimates the stretch factor (`eps`) and/or time shift (`dt`) that best realign a measured signal with a reference, and reports the remaining decorrelation.
+
+Developed as part of WP3, Deliverable D3.3.
+
+---
+
+## Installation
+
+Requirements: **Python ≥ 3.11** (dependencies: `numpy`, `scipy`)
+
+```bash
+pip install tc-cwi
+```
+
+---
+
+## Quickstart
+
+```python
+import numpy as np
+from tc_cwi import tc_cwi
+
+t = np.linspace(0, 1e-3, 1000)
+reference = np.sin(2 * np.pi * 50e3 * t)
+current = np.sin(2 * np.pi * 50e3 * t * (1 + 1e-4))  # slightly stretched
+
+# Correlation coefficient without compensation (one value per signal)
+baseline = tc_cwi("getccns", reference, current)
+print(f"Baseline CC: {baseline.CC[0]:.4f}")
+
+# Optimal stretch factor (Nelder-Mead from eps = 0) and remaining decorrelation
+result = tc_cwi("findeps", reference, current, t, 0.0, 2)
+print(f"eps: {result.eps:.6e}, decorrelation after stretching: {result.DC:.2e}")
+```
+
+Several signals can be processed at once by passing a 2D array with **one signal per column** (`n_samples × n_signals`):
+
+```python
+signals = np.column_stack([current, current, current])
+batch = tc_cwi("findeps", reference, signals, t, (-1e-2, 1e-2))  # bounded search
+print(batch.EPSf, batch.DCsf)
+```
+
+---
+
+## API
+
+The package exposes two layers.
+
+### MATLAB-compatible dispatch: `tc_cwi(cmd, *args, **kwargs)`
+
+Mirrors the original MATLAB toolbox. Results are returned as a `Struct` (`types.SimpleNamespace`), so fields are accessed MATLAB-style with `out.field`.
+
+| Command | Arguments | Output fields (single signal / multiple signals) |
+|---|---|---|
+| `getccns` | `y0, y1, ind=None` | `CC`, `DC` |
+| `getccs` | `y0, y1, t, eps, ind=None` | `CC`, `DC` |
+| `getccdt` | `y0, y1, t, dt, ind=None` | `CC`, `DC` |
+| `getccepsdt` | `y0, y1, t, eps, dt, ind=None` | `CC`, `DC` |
+| `getdcs` / `getdcdt` / `getdcepsdt` | same as `getcc*` | `DC` array (returned directly) |
+| `findeps` | `y1, y2, t, e0, method=1, ind=None` | `eps, DC, y, y0` / `EPSf, DCsf, ysf, y0` |
+| `finddt` | `y1, y2, t, dt0, method=1, ind=None` | `dt, DC, y, y0` / `DTf, DCdtf, ydtf, y0` |
+| `findepsdt` | `y1, y2, t, e0, dt0, method=2, ind=None` | `eps, dt, DC, y, y0` / `EPSf, DTf, DCsdtf, ysdtf, y0` |
+| `findeps -ma` | `y1, y2, t, e0, method=1, ind=None, ma=5` | multiple signals only: `EPSma, DCma, ysma, y0, yma` |
+| `stretch` | `y, t, eps` | stretched signal |
+| `shift` | `y, t, dt, method="interp"` | shifted signal (`"point"`, `"interp"` or `"fft"`) |
+| `stretchshift` | `y, t, eps, dt` | shifted, then stretched signal |
+
+Conventions:
+
+- **`CC`** is the absolute Pearson correlation coefficient, **`DC = 1 - CC`** the decorrelation.
+- **`ind`** restricts the correlation to a window (index array or slice). The stretch/shift is always applied to the full signal.
+- **`method`** selects the optimizer:
+  - `1`: bounded scalar search, the start value is an interval `(lower, upper)`.
+  - `2`: Nelder-Mead, the start value is a starting point. `findepsdt` only supports this method.
+
+  When processing several signals, each fit is seeded with the result of the previous one.
+- **`eps > 0`** compresses the wave (`t → t·(1+eps)`), **`dt > 0`** moves it forward (`t → t−dt`).
+- **`findeps -ma`** compares each signal against the mean of the last `ma` compensated signals instead of a fixed reference. `ma` is either a window size, or the `yma` returned by a previous call to continue the same window.
+
+### Core functions
+
+For direct use in Python code, without the MATLAB-style dispatch:
+
+| Function | Description |
+|---|---|
+| `correlation_coefficient(y0, y1)` | Absolute correlation coefficient between two signals |
+| `stretch(y, t, eps)` | Stretch a signal (not-a-knot cubic spline, zero outside `t`) |
+| `shift(y, t, dt, method="interp")` | Shift a signal by `dt` |
+| `stretchshift(y, t, eps, dt)` | Shift, then stretch a signal |
+| `find_optimum(y0, y, t, process, x0, method=1, ind=None, xatol=1e-8)` | Parameters of `process(y, t, *x)` minimizing the decorrelation with `y0`; returns `(x, decorrelation)` |
+| `MovingAverageReference(n, y_init=None)` | Rolling window of the last `n` signals; `.reference` is their mean, `.update(y)` adds a signal |
+
+```python
+from tc_cwi import find_optimum, stretch
+
+x, decorrelation = find_optimum(reference, current, t, stretch, (-1e-2, 1e-2))
+```
+
+---
+
+## Development
+
+This project uses [`uv`](https://github.com/astral-sh/uv) with the `uv_build` backend:
+
+```bash
+git clone https://github.com/Zensor-BE/tc-cwi.git
+cd tc-cwi
+uv sync
+```
+
+```text
+├── src/tc_cwi/
+│   ├── __init__.py      # Public API
+│   ├── core.py          # Stretching, shifting and optimization
+│   └── matlab.py        # MATLAB-compatible tc_cwi() dispatch
+├── tests/
+│   ├── test_core.py     # Core functions
+│   ├── test_matlab.py   # Every tc_cwi command: fields and error paths
+│   └── test_package.py  # Public API
+└── pyproject.toml
+```
+
+Tests, coverage and linting:
+
+```bash
+uv run pytest
+uv run pytest --cov   # statements + branches, with the missing lines
+uv run ruff check .
+```
+
+Releasing to PyPI: bump `version` in `pyproject.toml`, then push a matching tag. The [publish workflow](https://github.com/Zensor-BE/tc-cwi/blob/main/.github/workflows/publish.yml) lints, builds, tests the built distributions and publishes them.
+
+```bash
+git tag -a v0.1.0 -m v0.1.0
+git push origin v0.1.0
+```
+
+---
+
+## License
+
+[MIT](https://github.com/Zensor-BE/tc-cwi/blob/main/LICENSE)

tc_cwi-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "tc-cwi"
+version = "0.1.0"
+description = "Python toolbox to apply EOC compensation algorithms to ultrasonic testing data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "coda wave interferometry",
+    "structural health monitoring",
+    "temperature compensation",
+    "time-stretching",
+    "ultrasonic",
+]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy",
+    "scipy",
+]
+
+[[project.authors]]
+name = "Arnaud Deraemaeker (ULB)"
+email = "Arnaud.Deraemaeker@ulb.be"
+
+[[project.authors]]
+name = "Damiano Gianotti (Zensor)"
+email = "damiano.gianotti@zensor.be"
+
+[[project.authors]]
+name = "Jasmien Hassanin (IZFP)"
+
+[[project.authors]]
+name = "Jitendra Kumar Sharma (ULB)"
+email = "jitendra.kumar.sharma@ulb.be"
+
+[[project.authors]]
+name = "Luigi Trezza (Airbus)"
+
+[[project.maintainers]]
+name = "Zensor"
+email = "support@zensor.be"
+
+[project.urls]
+Repository = "https://github.com/Zensor-BE/tc-cwi"
+Issues = "https://github.com/Zensor-BE/tc-cwi/issues"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "B",
+    "I",
+    "UP",
+    "C4",
+    "FURB122",
+    "RUF015",
+    "RUF022",
+    "RUF046",
+]
+
+[tool.coverage.run]
+source = ["tc_cwi"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true

tc_cwi-0.1.0/pyproject.toml.orig

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "tc-cwi"
+version = "0.1.0"
+description = "Python toolbox to apply EOC compensation algorithms to ultrasonic testing data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name="Arnaud Deraemaeker (ULB)", email="Arnaud.Deraemaeker@ulb.be" },
+    { name="Damiano Gianotti (Zensor)", email="damiano.gianotti@zensor.be" },
+    { name="Jasmien Hassanin (IZFP)" },
+    { name="Jitendra Kumar Sharma (ULB)", email="jitendra.kumar.sharma@ulb.be" },
+    { name="Luigi Trezza (Airbus)" },
+]
+maintainers = [
+    { name="Zensor", email="support@zensor.be" },
+]
+keywords = [
+    "coda wave interferometry",
+    "structural health monitoring",
+    "temperature compensation",
+    "time-stretching",
+    "ultrasonic",
+]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy",
+    "scipy",
+]
+
+[project.urls]
+Repository = "https://github.com/Zensor-BE/tc-cwi"
+Issues = "https://github.com/Zensor-BE/tc-cwi/issues"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+
+# Explicit rule set: ruff's implicit defaults grow between releases, so this gate
+# spells out what it checks and must not start failing on an unrelated `uv sync`.
+# SIM is kept out on purpose (it prefers `T[-1] < T * 1.2` over `T * 1.2 > T[-1]`).
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E4", "E7", "E9", "F",     # pycodestyle (errors) + pyflakes
+    "B",                        # bugbear
+    "I", "UP", "C4",            # import order, modern syntax, comprehensions
+    "FURB122", "RUF015", "RUF022", "RUF046",  # the few specific rules worth their noise
+]
+
+[tool.coverage.run]
+source = ["tc_cwi"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true

tc_cwi-0.1.0/src/tc_cwi/__init__.py

@@ -0,0 +1,20 @@
+from .core import (
+    MovingAverageReference,
+    correlation_coefficient,
+    find_optimum,
+    shift,
+    stretch,
+    stretchshift,
+)
+from .matlab import Struct, tc_cwi
+
+__all__ = [
+    "MovingAverageReference",
+    "Struct",
+    "correlation_coefficient",
+    "find_optimum",
+    "shift",
+    "stretch",
+    "stretchshift",
+    "tc_cwi",
+]

tc_cwi-0.1.0/src/tc_cwi/core.py

@@ -0,0 +1,114 @@
+from collections import deque
+from collections.abc import Callable
+from typing import Literal
+
+import numpy as np
+from scipy.interpolate import interp1d
+from scipy.optimize import minimize, minimize_scalar
+
+FloatDType = np.dtype[np.float64]
+
+Array1D = np.ndarray[tuple[int], FloatDType]
+Array2D = np.ndarray[tuple[int, int], FloatDType]
+IndexArray = np.ndarray[tuple[int], np.dtype[np.int_]]
+
+ShiftMethodOptions = Literal["point", "interp", "fft"]
+
+
+def _interp1d(y: Array1D, t: Array1D, t_new: Array1D) -> Array1D:
+    """Not-a-knot cubic spline (MATLAB 'spline'), 0 outside of t."""
+    return interp1d(
+        t,
+        y,
+        kind="cubic",
+        bounds_error=False,
+        fill_value=0.0,
+        assume_sorted=True,
+    )(t_new)
+
+
+def correlation_coefficient(y0: Array1D, y1: Array1D) -> float:
+    return abs(np.corrcoef(y0, y1)[0, 1])
+
+
+def stretch(y: Array1D, t: Array1D, eps: float) -> Array1D:
+    """Stretch the full signal, t -> t*(1+eps). eps > 0 compresses the wave."""
+    return _interp1d(y, t, t * (1 + eps))
+
+
+def shift(
+    y: Array1D, t: Array1D, dt: float, method: ShiftMethodOptions = "interp"
+) -> Array1D:
+    """Shift the full signal, t -> t-dt. dt > 0 moves the wave forward."""
+    if method == "point":  # round half away from zero, like MATLAB
+        n = int(np.copysign(np.floor(abs(dt / (t[1] - t[0])) + 0.5), dt))
+        return np.roll(y, n)
+    if method == "interp":
+        return _interp1d(y, t, t - dt)
+    if method == "fft":
+        freqs = np.fft.fftfreq(len(y), d=t[1] - t[0])
+        return np.fft.ifft(np.fft.fft(y) * np.exp(-2j * np.pi * freqs * dt)).real
+    raise ValueError(f"Unknown shift method: {method!r}")
+
+
+def stretchshift(y: Array1D, t: Array1D, eps: float, dt: float) -> Array1D:
+    """Shift (interp) then stretch."""
+    return stretch(shift(y, t, dt), t, eps)
+
+
+def find_optimum(
+    y0: Array1D,
+    y: Array1D,
+    t: Array1D,
+    process: Callable[..., Array1D],
+    x0: float | Array1D,
+    method: Literal[1, 2] = 1,
+    ind: IndexArray | slice | None = None,
+    xatol: float = 1e-8,
+) -> tuple[Array1D, float]:
+    """
+    Find the parameters x minimizing the decorrelation (1 - CC) between y0 and
+    process(y, t, *x). Correlation is computed over `ind` only; process is
+    applied to the full signal. Returns (x, decorrelation).
+
+    - method 1: bounded scalar minimization, x0 = (lower, upper)
+    - method 2: Nelder-Mead, x0 = starting point (one value per parameter)
+    """
+    ind = slice(None) if ind is None else ind
+
+    def decorrelation(x) -> float:
+        processed = process(y, t, *np.atleast_1d(x))
+        return 1 - correlation_coefficient(y0[ind], processed[ind])
+
+    if method == 1:
+        res = minimize_scalar(
+            decorrelation,
+            bounds=tuple(x0),
+            method="bounded",
+            options={"xatol": xatol},
+        )
+    else:
+        res = minimize(
+            decorrelation,
+            np.atleast_1d(x0),
+            method="Nelder-Mead",
+            options={"xatol": xatol, "fatol": 1e-4},
+        )
+    return np.atleast_1d(res.x), res.fun
+
+
+class MovingAverageReference:
+    """Rolling window of the last `n` signals; their mean is the reference."""
+
+    def __init__(self, n: int, y_init: Array1D | None = None):
+        self.n = n
+        self.signals: deque[Array1D] = deque(maxlen=n)
+        if y_init is not None:
+            self.signals.append(y_init)
+
+    @property
+    def reference(self) -> Array1D:
+        return np.mean(self.signals, axis=0)
+
+    def update(self, y: Array1D) -> None:
+        self.signals.append(y)  # the oldest signal is dropped when full

tc_cwi-0.1.0/src/tc_cwi/matlab.py

@@ -0,0 +1,163 @@
+"""
+tc_cwi: MATLAB-compatible API
+"""
+
+from types import SimpleNamespace as Struct
+
+import numpy as np
+
+from .core import (
+    MovingAverageReference,
+    correlation_coefficient,
+    find_optimum,
+    shift,
+    stretch,
+    stretchshift,
+)
+
+
+def _getcc(process, y0, y1, *params, ind=None) -> Struct:
+    """out.CC / out.DC; process(column, *params) is applied on the full signal,
+    correlation on ind only; params may be scalars or one value per column."""
+    ind = slice(None) if ind is None else ind
+    columns = y1[:, None] if y1.ndim == 1 else y1
+    params = [np.broadcast_to(p, columns.shape[1]) for p in params]
+    cc = np.array(
+        [
+            correlation_coefficient(
+                y0[ind], process(columns[:, i], *(p[i] for p in params))[ind]
+            )
+            for i in range(columns.shape[1])
+        ]
+    )
+    return Struct(CC=cc, DC=1 - cc)
+
+
+def getccns(y0, y1, ind=None):
+    return _getcc(lambda y: y, y0, y1, ind=ind)
+
+
+def getccs(y0, y1, t, eps, ind=None):
+    return _getcc(lambda y, e: stretch(y, t, e), y0, y1, eps, ind=ind)
+
+
+def getccdt(y0, y1, t, dt, ind=None):
+    return _getcc(lambda y, d: shift(y, t, d), y0, y1, dt, ind=ind)
+
+
+def getccepsdt(y0, y1, t, eps, dt, ind=None):
+    return _getcc(lambda y, e, d: stretchshift(y, t, e, d), y0, y1, eps, dt, ind=ind)
+
+
+def getdcs(y0, y1, t, eps, ind=None):
+    return getccs(y0, y1, t, eps, ind).DC
+
+
+def getdcdt(y0, y1, t, dt, ind=None):
+    return getccdt(y0, y1, t, dt, ind).DC
+
+
+def getdcepsdt(y0, y1, t, eps, dt, ind=None):
+    return getccepsdt(y0, y1, t, eps, dt, ind).DC
+
+
+def _find(y1, y2, t, process, x0, method, ind, xatol):
+    """Fit one signal or each column of y2 in turn. The starting point of each
+    fit comes from the previous one (method 1: interval re-centered on it).
+    Returns xs (n, n_params), DCs (n,) and processed signals (N, n)."""
+    x0 = np.asarray(x0, dtype=float)
+    xs, dcs, ys = [], [], []
+    for y in (y2[:, None] if y2.ndim == 1 else y2).T:
+        x, dc = find_optimum(y1, y, t, process, x0, method, ind, xatol)
+        x0 = x0 - x0.mean() + x if method == 1 else x
+        xs.append(x), dcs.append(dc), ys.append(process(y, t, *x))
+    return np.array(xs), np.array(dcs), np.array(ys).T
+
+
+def findeps(y1, y2, t, e0, method=1, ind=None):
+    xs, dcs, ys = _find(y1, y2, t, stretch, e0, method, ind, 1e-8)
+    if y2.ndim == 1:
+        return Struct(eps=xs[0, 0], DC=dcs[0], y=ys[:, 0], y0=y1)
+    return Struct(DCsf=dcs, EPSf=xs[:, 0], ysf=ys, y0=y1)
+
+
+def finddt(y1, y2, t, dt0, method=1, ind=None):
+    xs, dcs, ys = _find(y1, y2, t, shift, dt0, method, ind, 1e-10)
+    if y2.ndim == 1:
+        return Struct(dt=xs[0, 0], DC=dcs[0], y=ys[:, 0], y0=y1)
+    return Struct(DCdtf=dcs, DTf=xs[:, 0], ydtf=ys, y0=y1)
+
+
+def findepsdt(y1, y2, t, e0, dt0, method=2, ind=None):
+    if method == 1:
+        raise ValueError("fminbnd is single variable, use method 2.")
+    x0 = [e0, dt0]
+    xs, dcs, ys = _find(y1, y2, t, stretchshift, x0, method, ind, 1e-8)
+    if y2.ndim == 1:
+        return Struct(eps=xs[0, 0], dt=xs[0, 1], DC=dcs[0], y=ys[:, 0], y0=y1)
+    return Struct(DCsdtf=dcs, DTf=xs[:, 1], EPSf=xs[:, 0], ysdtf=ys, y0=y1)
+
+
+def findeps_ma(y1, y2, t, e0, method=1, ind=None, ma: MovingAverageReference | int = 5):
+    """
+    ma: window size n (MATLAB ma.init=true, window seeded with y1) or the
+    out.yma of a previous call (ma.init=false; y1 is then the first reference).
+    """
+    if y2.ndim == 1:
+        raise ValueError("not for single signal")
+    if isinstance(ma, int):
+        ma = MovingAverageReference(ma, y1)
+
+    x = np.asarray(e0, dtype=float)
+    dc, eps = np.zeros(y2.shape[1]), np.zeros(y2.shape[1])
+    ys, refs = np.zeros_like(y2), np.zeros_like(y2)
+    y0 = y1
+    for i in range(y2.shape[1]):
+        res = findeps(y0, y2[:, i], t, x, method, ind)
+        eps[i], dc[i], ys[:, i] = res.eps, res.DC, res.y
+        x = x - x.mean() + eps[i] if method == 1 else np.atleast_1d(eps[i])
+        ma.update(ys[:, i])
+        y0 = refs[:, i] = ma.reference
+    return Struct(DCma=dc, EPSma=eps, ysma=ys, y0=refs, yma=ma)
+
+
+def tc_cwi(cmd: str, *args, **kwargs):
+    """
+    Time-Stretching and Coda Wave Interferometry (CWI) command dispatch.
+
+    Returns a Struct (SimpleNamespace) supporting attribute access (out.field),
+    mirroring MATLAB struct behavior.
+
+    Commands
+    --------
+    'getccns'      - Cross-correlation without stretching.
+    'getccs'       - Cross-correlation after stretching.
+    'getccdt'      - Cross-correlation after time shift.
+    'getccepsdt'   - Cross-correlation after stretch and time shift.
+    'findeps'      - Find optimal stretch factor eps minimising decorrelation.
+    'findeps -ma'  - Find optimal stretch factor eps using moving-average reference.
+    'finddt'       - Find optimal time shift dt minimising decorrelation.
+    'findepsdt'    - Joint optimization for eps and dt.
+    'stretch'      - Apply stretch factor eps to signal(s).
+    'shift'        - Apply time shift dt to signal(s).
+    'stretchshift' - Apply time shift then stretch to signal(s).
+    """
+    dispatch = {
+        "finddt": finddt,
+        "findeps": findeps,
+        "findeps -ma": findeps_ma,
+        "findepsdt": findepsdt,
+        "getccdt": getccdt,
+        "getccepsdt": getccepsdt,
+        "getccns": getccns,
+        "getccs": getccs,
+        "getdcdt": getdcdt,
+        "getdcepsdt": getdcepsdt,
+        "getdcs": getdcs,
+        "shift": shift,
+        "stretch": stretch,
+        "stretchshift": stretchshift,
+    }
+    if cmd not in dispatch:
+        raise ValueError(f"Unknown command: '{cmd}'")
+    return dispatch[cmd](*args, **kwargs)