### Quick start with APMD and OVMD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Example usage of the APMD and OVMD decomposition algorithms.

```python
from pysdkit import APMD, OVMD

modes_apmd = APMD(n_modes=5).fit_transform(signal, fs=fs)
modes_ovmd = OVMD(alpha=100, K=5).fit_transform(signal)
```

--------------------------------

### Run classic command

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/emd_variants/eemd.html

Command to run the classic example.

```text
run classic

```

--------------------------------

### Install PySDKit from source

Source: https://pysdkit.readthedocs.io/en/latest/user_guide/index.html

Commands to clone the repository and install it in editable mode for development.

```bash
git clone https://github.com/wwhenxuan/PySDKit.git
cd PySDKit
pip install -e .
```

--------------------------------

### Install scikit-learn

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/2fb0f67702479905408a191d431f49ad/emd_forecasting.ipynb

Install the scikit-learn package, required for the forecasting models used in the notebook.

```bash
pip install scikit-learn
```

--------------------------------

### Clone and install PySDKit from source

Source: https://pysdkit.readthedocs.io/en/latest/development/index.html

Clones the PySDKit repository, changes into the directory, installs the package in editable mode, and installs documentation requirements.

```bash
git clone https://github.com/wwhenxuan/PySDKit.git
cd PySDKit
pip install -e .
pip install -r docs/requirements.txt

```

--------------------------------

### Unified Interface Example

Source: https://pysdkit.readthedocs.io/en/latest/user_guide/index.html

Demonstrates the standard workflow: importing an algorithm, initializing it, fitting the model, and plotting the results.

```python
from pysdkit import VMD
from pysdkit.data import test_vmd
from pysdkit.plot import plot_IMFs

t, signal, fs = test_vmd()
vmd = VMD(alpha=2000, K=4, tau=0.0, tol=1e-7)
IMFs = vmd.fit_transform(signal)
plot_IMFs(signal, IMFs, view="2d_freq", fs=fs, freq_max=fs / 2)
```

--------------------------------

### Install PySDKit via pip

Source: https://pysdkit.readthedocs.io/en/latest/user_guide/index.html

Standard installation command for the PySDKit package.

```bash
pip install pysdkit
```

--------------------------------

### CEEMDAN output example

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/emd_variants/ceemdan.html

Example console output showing the shape of the resulting cIMFs and the reconstruction error.

```text
cIMFs (+ residue): (5, 600)
complete reconstruction error: 4.440892098500626e-16
run classic
```

--------------------------------

### Quick start with DD_ACMD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to import the DD_ACMD class and a stationary demo generator to perform decomposition on a signal.

```python
from pysdkit import DD_ACMD
from pysdkit._acmd.dd_acmd import generate_stationary_demo

demo = generate_stationary_demo(fs=300.0, duration=1.0, noise_std=0.3)
dd = DD_ACMD(fs=300.0)
imfs = dd.fit_transform(demo["signal"])
# or: imfs, ini_if, e_if, e_ia = dd.fit_transform(..., return_all=True)
```

--------------------------------

### Quick start with PySDKit algorithms

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates basic usage of MEMD, EMD2D, VME, and ITD algorithms using provided test data.

```python
from pysdkit import MEMD, EMD2D, VME, ITD
from pysdkit.data import load_memd_syn_hex, test_univariate_signal, test_univariate_image

# Multivariate EMD (channels x time)
hex_sig = load_memd_syn_hex()["signal"]          # (6, 1001)
imfs = MEMD(n_dir=64)(hex_sig)                   # (K, 1001, 6)

# 2-D EMD of a grayscale image
image = test_univariate_image()
bimfs = EMD2D(max_imfs=3).fit_transform(image)   # (K, H, W)

# Variational Mode Extraction
from pysdkit.data import test_emd
t, x = test_emd()
u, omega = VME(alpha=2000, fs=1000.0).fit_transform(x, omega_init=36.0)

# Intrinsic Time-Scale Decomposition
_, x1 = test_univariate_signal(case=1)
prcs = ITD(N_max=10)(x1)                         # last row = residue
```

--------------------------------

### Importing HVD and dependencies

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/92de4c0aa905b79bd70d73e666a157a9/hvd.ipynb

Initial setup importing necessary libraries and the HVD class from pysdkit.

```python
import numpy as np
import matplotlib.pyplot as plt
from scipy.signal import hilbert

from pysdkit import HVD
from pysdkit.plot import plot_IMFs

print(HVD())
```

--------------------------------

### Quick start with IMD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to load demo data and perform Impulsive Mode Decomposition using the IMD class.

```python
from pysdkit import IMD
from pysdkit._imd import load_imd_input_sig

demo = load_imd_input_sig()
imd = IMD(n_particles=45, max_iter=20, threshold=1.60, max_modes=4, seg_num=10, seed=0)
modes = imd.fit_transform(demo["signal"], fs=demo["fs"])
# or: out = imd.fit_transform(..., return_all=True)
```

--------------------------------

### Quick start with NSTEMD and OnlineEMD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to import and initialize the new NSTEMD and OnlineEMD classes, including loading sample ECG data.

```python
from pysdkit import NSTEMD, OnlineEMD
from pysdkit.data import load_oemd_ecg

# NS-TEMD: (n_channels, n_samples) -> (n_imfs, n_samples, n_channels)
nstemd = NSTEMD(n_dir=32)
# imfs = nstemd(signal_ct)

# Online EMD: univariate stream or batch
ecg = load_oemd_ecg()["signal"]
imfs = OnlineEMD(n_extrema=10, emd_algo="fix_h")(ecg)
```

--------------------------------

### Quick start with IVGNMD, LMD, and RLMD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates basic usage of the IVGNMD, LMD, and RLMD algorithms for signal decomposition.

```python
from pysdkit import IVGNMD, LMD, RLMD

# Improved VGNMD for crossed chirps
imfs = IVGNMD()(signal)

# Classical / robust local mean decomposition
pfs = LMD()(signal)
pfs, ams, fms = RLMD(max_imfs=10, max_iter=30)(signal, return_all=True)
```

--------------------------------

### DDIFI initialization output

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/acmd/dd_acmd.html

The expected console output when running the DDIFI initialization example.

```text
median init IF ≈ 35.73 Hz (target 35 Hz)
```

--------------------------------

### Build HTML documentation with Sphinx

Source: https://pysdkit.readthedocs.io/en/latest/development/index.html

Builds the HTML documentation using Sphinx. The output is in docs/build/html/index.html. Read the Docs uses the same Sphinx config and installs the checkout with pip install . (see .readthedocs.yaml).

```bash
sphinx-build -b html docs/source docs/build/html

```

--------------------------------

### Quick start with VMD and Entropy

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to import modules, perform Variational Mode Decomposition (VMD), and calculate spectral and sample entropy on the resulting IMFs.

```python
from pysdkit import VMD
from pysdkit.data import test_vmd
from pysdkit.entropy import spectral_entropy, sample_entropy
from pysdkit.utils import BSS

t, x, fs = test_vmd()
imfs = VMD(alpha=2000, K=4, tau=0.0, tol=1e-7).fit_transform(x)
print(spectral_entropy(imfs[0]), sample_entropy(imfs[0], m=2, r=0.2))

# Underdetermined BSS: mix, cluster frequency energy, recover sources
# y = BSS(num=2).fit_transform(mixture)  # see examples/utils/bss.py
```

--------------------------------

### Run MATLAB Example 3 (parts a and b)

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/vmd/vme.html

Reproduces example 3 from the paper: Eq. (25) with a linear chirp and a jumping tone. Extracts the chirp (3a) with omega_init=6 Hz and the first piecewise tone (3b) with omega_init=26 Hz. Expected output: Example 3a: n_iter=20, omega = 10.030 Hz and Example 3b: n_iter=7, omega = 30.087 Hz.

```python
mode3a, omega3a = run_demo(generate_vme_example3a())
mode3b, omega3b = run_demo(generate_vme_example3b())
```

```text
Example 3a: n_iter=20, omega = 10.030 Hz
Example 3b: n_iter=7, omega = 30.087 Hz
```

--------------------------------

### Run MATLAB Example 2

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/vmd/vme.html

Reproduces example 2 from the paper: Eq. (24) with a 2 Hz tone and two AM tones at 15 Hz and 40 Hz. Extracts the 15 Hz component with omega_init = 10 Hz. Expected output: n_iter=7, omega = 14.997 Hz.

```python
demo2 = generate_vme_example2()
mode2, omega2 = run_demo(demo2)
```

```text
Example 2: n_iter=7, omega = 14.997 Hz
```

--------------------------------

### Importing STVMD and VMD libraries

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/e2a140d2cb5baf2b2d3d570a9ed7967f/stvmd.ipynb

Initial setup for the environment, importing necessary libraries and configuring matplotlib parameters.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit import STVMD, VMD

plt.rcParams["figure.dpi"] = 120
plt.rcParams["font.size"] = 11
```

--------------------------------

### PySDKit VMD2D full example with visualization

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/image/vmd2d.html

A complete example that loads a synthetic texture, defines helper functions for relative error, mode visualization, spectrum magnitude, and extracting the final omega, then runs VMD2D and displays the input image and its spectrum.

```python
import numpy as np
import matplotlib.pyplot as plt
from numpy.fft import fft2, fftshift

from pysdkit import VMD2D
from pysdkit.data import test_grayscale, test_univariate_image, get_meshgrid_2D
from pysdkit.plot import plot_grayscale_image, plot_grayscale_spectrum

plt.rcParams.update(
    {
        "figure.dpi": 120,
        "font.size": 11,
        "axes.grid": False,
    }
)


def relative_error(ref, est):
    ref = np.asarray(ref, dtype=float)
    est = np.asarray(est, dtype=float)
    return np.linalg.norm(est - ref) / (np.linalg.norm(ref) + 1e-16)


def show_modes(modes, titles=None, cmap="gray", vmax=None):
    # modes: (H, W, K)
    K = modes.shape[2]
    fig, axs = plt.subplots(1, K, figsize=(2.4 * K, 2.6))
    if K == 1:
        axs = [axs]
    for k in range(K):
        lim = vmax if vmax is not None else np.percentile(np.abs(modes[:, :, k]), 99)
        axs[k].imshow(modes[:, :, k], cmap=cmap, vmin=-lim, vmax=lim)
        axs[k].set_title(titles[k] if titles else f"Mode {k+1}")
        axs[k].axis("off")
    plt.tight_layout()
    return fig, axs


def spectrum_mag(img):
    return np.abs(fftshift(fft2(img)))


def final_omega(omega):
    # omega: (max_iter, 2, K) -> last written (2, K)
    for i in range(omega.shape[0] - 1, -1, -1):
        if np.any(omega[i] != 0) or i == 0:
            return np.asarray(omega[i], dtype=float)
    return np.asarray(omega[-1], dtype=float)


img = test_grayscale()
print("Paper synthetic texture shape:", None if img is None else img.shape)
fig, axs = plt.subplots(1, 2, figsize=(8, 3.6))
axs[0].imshow(img, cmap="gray")
axs[0].set_title("Synthetic texture f_synth")
axs[0].axis("off")
axs[1].imshow(np.log1p(spectrum_mag(img)), cmap="magma")
axs[1].set_title("log(1+|FFT|)")
axs[1].axis("off")
plt.tight_layout()
plt.show()

```

--------------------------------

### Quick start with OSD presets

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Basic usage of the OSD class using a preset configuration to decompose a signal.

```python
from pysdkit import OSD

# preset: residual + smooth trend + total-variation jumps
osd = OSD.preset("convex_demo", length=len(y), max_iter=120)
X = osd.fit_transform(y)   # shape: (K, N)
```

--------------------------------

### Run MATLAB Example 1

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/vmd/vme.html

Reproduces example 1 from the paper (Eq. 23) with a slow AM carrier plus FM burst. Targets the lowest mode by setting omega_init = 0 Hz. Expected output: n_iter=6, omega = 0.390 Hz.

```python
demo1 = generate_vme_example1()
mode1, omega1 = run_demo(demo1)
```

```text
Example 1: n_iter=6, omega = 0.390 Hz
```

--------------------------------

### Import SWD and dependencies

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/59acd024def169bf68573bfa86e47bd0/swd.ipynb

Imports necessary libraries and the SWD class, then prints the SWD object to verify installation.

```python
import numpy as np
import matplotlib.pyplot as plt
from scipy.signal.windows import hann

from pysdkit import SWD, swd
from pysdkit._osd.swd import swf_params_from_frequency, bandpass_swf

print(SWD())
```

--------------------------------

### VMD on packaged multi-component example (README example 2)

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/demo.html

Uses the packaged helper test_vmd() to obtain a multi-component signal, applies Variational Mode Decomposition (VMD) with alpha=2000, K=4, tau=0.0, tol=1e-7, and plots the resulting IMFs. VMD estimates band-limited modes and center frequencies jointly in the Fourier domain.

```python
t_v, signal_v, fs_v = test_vmd()

vmd = VMD(alpha=2000, K=4, tau=0.0, tol=1e-7)
IMFs_v = vmd.fit_transform(signal_v)
plot_IMFs(signal_v, IMFs_v, view="2d_freq", fs=fs_v, freq_max=fs_v / 2)
plt.suptitle("VMD — packaged multi-component example (README)", y=1.02)
plt.tight_layout()
plt.show()

```

--------------------------------

### Setup and Helper Functions

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/e8b36fa5aef2c4cd76129fe8bb9d7a94/vncmd.ipynb

Initializes plotting parameters and defines helper functions for calculating relative error and signal-to-noise ratio (SNR).

```python
import numpy as np
import matplotlib.pyplot as plt
from numpy.fft import fft, fftshift, fftfreq

from pysdkit import VNCMD

plt.rcParams.update(
    {
        "figure.dpi": 120,
        "font.size": 11,
        "axes.grid": True,
        "grid.alpha": 0.25,
    }
)


def relative_error(ref, est):
    ref = np.asarray(ref, dtype=float)
    est = np.asarray(est, dtype=float)
    return float(np.linalg.norm(est - ref) / (np.linalg.norm(ref) + 1e-16))


def snr_db(clean, estimate):
    clean = np.asarray(clean, dtype=float)
    estimate = np.asarray(estimate, dtype=float)
    return float(
        10 * np.log10(np.sum(clean**2) / (np.sum((clean - estimate) ** 2) + 1e-16))
    )
```

--------------------------------

### Importing pysdkit and dependencies

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/37ad7f9245643db15fcb8855c2a06c3b/memd_filter.ipynb

Initial setup for the MEMD implementation, including necessary numerical and plotting libraries.

```python
import numpy as np
import matplotlib.pyplot as plt
from scipy.interpolate import CubicSpline

from pysdkit import MEMD
from pysdkit.data import load_memd_syn_hex

print(MEMD())
```

--------------------------------

### FAEMD Usage Example

Source: https://pysdkit.readthedocs.io/en/latest/_modules/pysdkit/_faemd/faemd.html

Demonstrates initializing FAEMD, processing a test signal, and plotting the resulting IMFs.

```python
if __name__ == "__main__":
    from matplotlib import pyplot as plt

    from pysdkit.data import test_emd, test_multivariate_signal
    from pysdkit.plot import plot_IMFs

    faemd = FAEMD(max_imfs=3)
    _, signal = test_emd()
    imfs = faemd.fit_transform(signal)
    plot_IMFs(signal, imfs)
    plt.show()
```

--------------------------------

### MVMD One-liner with PySDKit

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/24f4c31036d49a0ef3fbc7b4801345bf/mvmd.ipynb

A concise example demonstrating how to initialize and execute the MVMD algorithm on a signal using the PySDKit library.

```python
from pysdkit import MVMD
modes = MVMD(alpha=2000, K=3, tau=0.0, init="uniform").fit_transform(signal)
```

--------------------------------

### Visualize Analytic Signal Components

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/d2d317e0cc3e0132b393650fe7bd5aee/hht.ipynb

This example demonstrates the Hilbert transform on a simple tone, visualizing the real signal, analytic signal components, envelope, and the complex plane representation.

```python
import numpy as np
import matplotlib.pyplot as plt
from scipy.signal import stft, hilbert as sp_hilbert

from pysdkit import HHT, EMD
from pysdkit.data import test_hht, test_univariate_duffing
from pysdkit.plot import plot_IMFs, plot_HilbertSpectrum
from pysdkit.utils import hilbert_transform, hilbert_spectrum
from pysdkit._emd.hht.frequency import get_envelope_frequency

plt.rcParams.update(
    {
        "figure.dpi": 120,
        "font.size": 11,
        "axes.grid": True,
        "grid.alpha": 0.25,
    }
)


def relative_error(ref, est):
    ref = np.asarray(ref, dtype=float)
    est = np.asarray(est, dtype=float)
    return np.linalg.norm(est - ref) / (np.linalg.norm(ref) + 1e-16)


# Simple tone: visualize analytic signal
fs0 = 500.0
t0 = np.arange(0, 1.0, 1.0 / fs0)
x0 = np.cos(2 * np.pi * 10 * t0) * np.exp(-2 * (t0 - 0.5) ** 2)
z0 = hilbert_transform(x0)

fig, axs = plt.subplots(2, 2, figsize=(10, 5.5))
axs[0, 0].plot(t0, x0, "k")
axs[0, 0].set_title("Real signal x(t)")
axs[0, 1].plot(t0, np.real(z0), label="Re")
axs[0, 1].plot(t0, np.imag(z0), label="Im = H{x}")
axs[0, 1].legend(fontsize=8)
axs[0, 1].set_title("Analytic signal components")
axs[1, 0].plot(t0, np.abs(z0), color="C3")
axs[1, 0].plot(t0, x0, "k", alpha=0.4)
axs[1, 0].set_title("Envelope a(t) = |z(t)|")
axs[1, 0].set_xlabel("Time [s]")
axs[1, 1].plot(np.real(z0), np.imag(z0), lw=0.8)
axs[1, 1].set_aspect("equal")
axs[1, 1].set_xlabel("Real")
axs[1, 1].set_ylabel("Imag")
axs[1, 1].set_title("Complex plane")
plt.tight_layout()
plt.show()
```

--------------------------------

### Perform MVMD sanity check

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/vmd/mvmd.html

A basic example demonstrating how to initialize MVMD, fit a multivariate signal, and calculate the reconstruction error.

```python
t0, s0 = test_multivariate_signal(case=1, duration=1.0, sampling_rate=1000)
print("input shape (C, T):", s0.shape)
mvmd0 = MVMD(alpha=2000, K=3, tau=0.0, init="uniform", tol=1e-7, max_iter=400)
u0 = mvmd0.fit_transform(s0)
print("modes shape (K, T, C):", u0.shape)
recon = u0.sum(axis=0).T  # (C, T)
print("relative recon. error:", relative_error(s0, recon))
```

--------------------------------

### Quick start with SET and blind deconvolution

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates initializing the SET transform for ridge reconstruction and applying blind deconvolution to a signal.

```python
from pysdkit import SET
from pysdkit.data import load_set_batdata2, load_imckd_sig1
from pysdkit.utils import imckd, acycbd, smhd

# SET: TFR, then ridge reconstruction (last row is the residual)
bat = load_set_batdata2()
te, freq = SET(hlength=50, fs=bat["fs"]).transform(bat["signal"])
imfs = SET(hlength=50, fs=bat["fs"], n_imfs=3)(bat["signal"])  # (4, T)

# Blind deconvolution: inverse FIR + period estimated on the fly
sig1 = load_imckd_sig1()
y, fir, info = imckd(sig1["signal"], fs=sig1["fs"])
```

--------------------------------

### Running ACYCBD demo

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/d0a610e4d32fec890a02371117e9a947/acycbd.ipynb

Example call to the ACYCBD function using the provided sig2 dataset.

```python
x, fs = load_acycbd_sig2()
s, h, alpha_hist = acycbd(x, fs, L=40)
```

--------------------------------

### Usage Example

Source: https://pysdkit.readthedocs.io/en/latest/_modules/pysdkit/tsa/_moving_decomp.html

Demonstrates how to use Moving_Decomp to process and visualize both univariate and multivariate time series data.

```python
if __name__ == "__main__":
    from pysdkit.data import generate_time_series

    # univariate time series
    time_series = generate_time_series()

    moving_decomp = Moving_Decomp(window_size=5)

    trends, seasonalities = moving_decomp.fit_transform(signal=time_series)

    moving_decomp.plot_decomposition(
        signal=time_series, trend=trends, seasonality=seasonalities
    )
    plt.show()

    # multivariate time series
    time_series = np.vstack([time_series] * 3)
```

--------------------------------

### VNCMD One-liner Usage

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/e8b36fa5aef2c4cd76129fe8bb9d7a94/vncmd.ipynb

A concise example of initializing and running the VNCMD decomposition in a single line.

```python
from pysdkit import VNCMD
modes, IF, IA = VNCMD(fs=fs, alpha=5e-6, beta=1e-6, var=0.0).fit_transform(x, eIF=iniIF)
```

--------------------------------

### Imports and setup for PySDKit demo

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/demo.html

Imports required libraries and PySDKit modules, sets matplotlib parameters, and prints a ready message. The output 'PySDKit demo ready' is shown.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit import EMD, VMD, MVMD, CEEMDAN, EEMD, VMD2D
from pysdkit.data import test_vmd, test_grayscale, test_univariate_image
from pysdkit.plot import plot_IMFs

plt.rcParams.update({"figure.dpi": 110, "font.size": 11})
print("PySDKit demo ready")

```

```text
PySDKit demo ready

```

--------------------------------

### VMD one-liner with PySDKit

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/b4517e3ac19ef95b13b217127cfc290f/vmd.ipynb

A concise example of how to initialize and apply VMD to a signal using PySDKit.

```python
from pysdkit import VMD
modes = VMD(alpha=2000, K=3, tau=0.0).fit_transform(signal)
```

--------------------------------

### Import LMD and setup plotting

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/lmd/lmd.html

Imports necessary libraries and the LMD class, sets matplotlib parameters, and prints the LMD object to show its default configuration.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit import LMD
from pysdkit.data import test_emd
from pysdkit.plot import plot_IMFs

plt.rcParams["figure.dpi"] = 120
plt.rcParams["font.size"] = 11
print(LMD())

```

--------------------------------

### Define custom OSD components

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Example of configuring OSD with custom components for specific signal decomposition tasks.

```python
from pysdkit import OSD
from pysdkit._osd import MeanSquareSmall, SparseSecondDiffConvex

osd = OSD(
    components=[
        MeanSquareSmall(size=len(y), weight=1 / len(y)),
        SparseSecondDiffConvex(weight=1.0),  # L1 trend filtering
    ],
    max_iter=80,
)
X = osd.fit_transform(y)
```

--------------------------------

### Import required libraries: numpy, matplotlib, and pysdkit functions

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/deconvolution/acycbd.html

Imports the necessary libraries for numerical processing, plotting, and the ACYCBD-related functions used in the example. Ensure pysdkit is installed.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit.data import load_acycbd_sig2
from pysdkit.utils import acycbd, annotate_harmonics, envelope_spectrum, matlab_kurtosis

```

--------------------------------

### EFD Decomposition Example 1

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/25665da18cb888da37875d3dfe367efd/efd.ipynb

Demonstrates the basic usage of EFD to decompose a signal into components, visualizing the results and spectrum boundaries.

```python
fs = 1000.0
t = np.arange(0.0, 1.0 + 1.0 / fs, 1.0 / fs)

f11 = 6.0 * t
f12 = 2.0 * np.cos(8.0 * np.pi * t)
f13 = np.cos(40.0 * np.pi * t)
f1 = f11 + f12 + f13

efd_1 = EFD(max_imfs=4)
imfs_1, cerf_1, bounds_1 = efd_1.fit_transform(f1, return_all=True)

print("f1 length:", f1.size)
print("IMF shape:", imfs_1.shape)
print("central frequencies (rad):", np.round(cerf_1, 4))
print("boundaries (rad):", np.round(bounds_1, 4))

fig, axes = plt.subplots(4, 1, figsize=(10, 7), sharex=True)
axes[0].plot(t, f1, color="k")
axes[0].set_ylabel(r"$f_1(t)$")
for ax, y, lab in zip(
    axes[1:], (f11, f12, f13), (r"$f_{11}$", r"$f_{12}$", r"$f_{13}$")
):
    ax.plot(t, y)
    ax.set_ylabel(lab)
axes[-1].set_xlabel("t (s)")
fig.suptitle("Example 1: components (Zhou et al., Fig. 4)")
fig.tight_layout()
plt.show()

fig, ax = plt.subplots(figsize=(8, 3.5))
plot_bounds(f1, bounds_1, ax=ax)
ax.set_title("Example 1: EFD spectrum boundaries (MATLAB plotbounds.m)")
fig.tight_layout()
plt.show()

plot_IMFs(f1, imfs_1, fs=fs)
plt.gcf().suptitle("Example 1: EFD modes", y=1.01)
plt.show()
```

--------------------------------

### Quick start: STNBMD decomposition with make_order_tracking_demo

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates the unified OOP fit_transform API for STNBMD. Creates a demo signal with make_order_tracking_demo, configures STNBMD parameters (alpha, beta, abitr, tol), and decomposes into modes. Optionally, return_all=True provides additional outputs (xnb, err, amp, phz).

```python
from pysdkit import STNBMD
from pysdkit._vncmd.stnbmd import make_order_tracking_demo

demo = make_order_tracking_demo(fs=100.0, nt=1000)
stn = STNBMD(
    fs=100.0,
    alpha=[1e-1, 1e-2, 1e-2],
    beta=[1.0, 1e-1, 1e-3],
    abitr=[20, 50, 200],
    tol=1e-6,
)
modes = stn.fit_transform(demo["signal"], frequencies=[2.0, 4.0, 6.0])  # (K, nt)
# or: modes, xnb, err, amp, phz = stn.fit_transform(..., return_all=True)
```

--------------------------------

### Example output for method comparison

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/emd/emd_denoising.html

This block displays the console output generated by the comparison script, showing SNR values for different signals and methods.

```text
=== Doppler input 1.98 dB
  EMD-Soft    :  12.02 dB
  EMD-Hard    :  12.02 dB
  EMD-SG      :   6.82 dB
  EMD-Median  :   7.63 dB
  EMD-Average :  10.28 dB
=== Blocks input 1.98 dB
  EMD-Soft    :  11.57 dB
  EMD-Hard    :  11.57 dB
  EMD-SG      :   6.77 dB
  EMD-Median  :   7.61 dB
  EMD-Average :  10.07 dB
=== Bumps input 1.98 dB
  EMD-Soft    :  13.11 dB
  EMD-Hard    :  13.11 dB
  EMD-SG      :   6.82 dB
  EMD-Median  :   7.82 dB
  EMD-Average :  10.39 dB
=== Heavysine input 1.98 dB
  EMD-Soft    :  14.96 dB
  EMD-Hard    :  14.96 dB
  EMD-SG      :   6.82 dB
  EMD-Median  :   7.80 dB
  EMD-Average :  10.39 dB

Method             Doppler      Blocks       Bumps   Heavysine
--------------------------------------------------------------
Noise                 1.98        1.98        1.98        1.98
EMD-Soft             12.02       11.57       13.11       14.96
EMD-Hard             12.02       11.57       13.11       14.96
EMD-SG                6.82        6.77        6.82        6.82
EMD-Median            7.63        7.61        7.82        7.80
EMD-Average          10.28       10.07       10.39       10.39

Paper Table I (reference, dB):
Noise      2.03 / 2.03 / 2.03 / 2.03
EMD-Soft  11.13 / 11.98 / 19.86 / 11.18
EMD-SG    13.57 / 12.00 / 20.60 / 14.50
(Exact numbers differ with EMD implementation / boundaries; trends should be similar.)
```

--------------------------------

### 1D EWT Output Example

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/ewt/ewt_ewt2d.html

Example output showing the shape of the extracted IMFs and the detected spectral boundaries.

```text
IMF shape (K, N): (3, 1000)
Detected boundaries (rad): [0.02199115 0.05654867]
```

--------------------------------

### Initialize and run VTFMTD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to load demo signal data and perform decomposition using the VTFMTD class.

```python
from pysdkit import VTFMTD
from pysdkit._tfa import load_dual_signal_noise

demo = load_dual_signal_noise()
vtf = VTFMTD(hlength=28, K=2, alpha=5e-5, sigma=0.01, beta=0.3)
Gk, omega = vtf.fit_transform(demo["signal"], omega_init=[250.0, 950.0])
# Gk: (F, T, K) mode STFTs; omega: IF field (MATLAB-style bin units)
```

--------------------------------

### Initialize and run APITMEMD

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to import the APITMEMD class and a sample dataset, then execute the decomposition on a signal.

```python
from pysdkit import APITMEMD
from pysdkit.data import load_apitmemd_section_2b

sig = load_apitmemd_section_2b()["signal"]  # (6, 360)
imfs = APITMEMD(n_dir=16, alpha=0.3)(sig)    # (K, 360, 6)
```

--------------------------------

### Quick start with SST and Fast Kurtogram

Source: https://pysdkit.readthedocs.io/en/latest/release_notes/index.html

Demonstrates how to perform SST decomposition on multivariate signals and use the Fast Kurtogram utility to identify and extract impulsive bands.

```python
from pysdkit import SST
from pysdkit.data import load_sst_float, load_fast_kurtogram_x
from pysdkit.utils import fast_kurtogram, find_wav_kurt

# SST: univariate (T,) or multivariate (C, T) -> IMFs
float_sig = load_sst_float()["signal"]          # (2, 1116)
imfs = SST(wavelet="bump")(float_sig)           # (K, 1116, 2)

# Fast kurtogram: map + peak band, then optional envelope
demo = load_fast_kurtogram_x()
Kwav, info = fast_kurtogram(demo["signal"], nlevel=7, fs=1.0)
env = find_wav_kurt(info["x"], info["level"], info["fc"] / info["fs"], fs=1.0)
```

--------------------------------

### Tensor EWT2D output example

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/ewt/ewt_ewt2d.html

Example output showing the shape and bounds resulting from the Tensor EWT2D fit_transform operation.

```text
modes shape: (9, 128, 128)
n_row x n_col = 3 x 3
row bounds: [0.17180585 0.3436117 ]
col bounds: [0.17180585 0.46633016]
```

--------------------------------

### Initialize and use STVMD class

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/e2a140d2cb5baf2b2d3d570a9ed7967f/stvmd.ipynb

Demonstrates how to import the STVMD class, initialize it with specific parameters, and perform signal decomposition using fit_transform.

```python
from pysdkit import STVMD, stvmd

st = STVMD(K=3, alpha=50, n_fft=64, dynamic=True)
modes = st.fit_transform(signal)                 # (K, T)
modes, u_hat, omega = st.fit_transform(signal, return_all=True)
```

--------------------------------

### Import libraries for SMHD example

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/98bd18b787497848d095f6faf053209c/smhd.ipynb

Imports required for the SMHD example: NumPy, Matplotlib, and pysdkit functions including load_smhd_sig3, envelope_spectrum, matlab_kurtosis, and smhd.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit.data import load_smhd_sig3
from pysdkit.utils import (
    annotate_harmonics,
    envelope_spectrum,
    matlab_kurtosis,
    peak_frequency,
    smhd,
)
```

--------------------------------

### Perform VMD and visualize results

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/b4517e3ac19ef95b13b217127cfc290f/vmd.ipynb

This example demonstrates how to decompose a signal using VMD, calculate reconstruction error, and visualize the resulting IMFs, amplitude spectra, and center-frequency convergence.

```python
t, signal = test_emd(duration=1.0, sampling_rate=1000, noise_level=0.08)
if signal.size % 2:
    t, signal = t[:-1], signal[:-1]

vmd = VMD(alpha=2000, K=3, tau=0.0, DC=True, tol=1e-7, max_iter=500)
modes, u_hat, omega = vmd.fit_transform(signal, return_all=True)

print("Final center frequencies (normalized):", np.round(omega[-1], 4))
print("Relative reconstruction error:", relative_error(signal, modes.sum(0)))

fig = plot_IMFs(signal, modes, return_figure=True)
fig.suptitle("VMD on the test_emd signal", y=1.01)
plt.show()

fig = plot_IMFs_amplitude_spectra(modes, return_figure=True)
fig.suptitle("Amplitude spectra of the modes", y=1.01)
plt.show()

# Center-frequency trajectories over ADMM iterations
fig, ax = plt.subplots(figsize=(8, 3.2))
n_iter = omega.shape[0]
for k in range(omega.shape[1]):
    ax.plot(np.arange(n_iter), omega[:, k] * 1000.0, lw=1.3, label=f"mode {k}")
ax.set_xlabel("Iteration")
ax.set_ylabel("Center frequency [Hz]")
ax.set_title("Center-frequency convergence")
ax.legend()
plt.tight_layout()
plt.show()
```

--------------------------------

### fmirror example

Source: https://pysdkit.readthedocs.io/en/latest/API/pysdkit.utils.html

Example usage of the fmirror function with a numpy array. The function mirrors 'sym' elements at both ends. The output shows the mirrored array.

```python
>>> array = np.array([1, 2, 3, 4, 5])
>>> fmirror(array, 2)
```

```text
array([2, 1, 1, 2, 3, 4, 5, 5, 4])
```

--------------------------------

### Compare Online EMD and Classical EMD

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/57ec9ab0fe5d9807a9b2b41187ddfc03/online_emd.ipynb

This example performs EMD on a signal using both the Online EMD and classical EMD algorithms, then visualizes the resulting IMFs.

```python
oemd = OnlineEMD(n_extrema=10, emd_algo=2)
imfs_on = oemd.fit_transform(x)
res_idx = residual_stage_index(oemd.stages)
L = oemd.stages[res_idx].data.size
recon = imfs_on[:, :L].sum(axis=0)

emd = EMD(max_imfs=3, FIXE_H=4)
imfs_off = emd.fit_transform(x, max_imfs=3)
print("Online EMD", imfs_on.shape, "committed residual length", L)
print("EMD      ", imfs_off.shape)
print("prefix recon max |error|", np.max(np.abs(recon - x[:L])))

n_show = min(4, imfs_on.shape[0], imfs_off.shape[0])
fig, axes = plt.subplots(n_show + 1, 2, figsize=(10, 1.2 * (n_show + 1)), sharex=True)
axes[0, 0].plot(x, color="0.2", lw=0.9)
axes[0, 0].set_title("Online EMD (FIX_H=4)")
axes[0, 0].set_ylabel("Data")
axes[0, 1].plot(x, color="0.2", lw=0.9)
axes[0, 1].set_title("Classical EMD (FIX_H=4)")
for k in range(n_show):
    axes[k + 1, 0].plot(imfs_on[k], lw=0.9)
    axes[k + 1, 1].plot(imfs_off[k], lw=0.9)
    label = (
        f"IMF {k + 1}"
        if k < n_show - 1 or imfs_on.shape[0] > n_show
        else ("Res." if k == imfs_on.shape[0] - 1 else f"IMF {k + 1}")
    )
    axes[k + 1, 0].set_ylabel(label)
    axes[k + 1, 0].axvline(L, color="crimson", ls="--", lw=0.8, alpha=0.8)
for ax in axes.ravel():
    ax.grid(True, alpha=0.25)
axes[-1, 0].set_xlabel("sample")
axes[-1, 1].set_xlabel("sample")
fig.tight_layout()
plt.show()
```

--------------------------------

### Output of damped FM tone example

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/tfa/set.html

The printed output from the damped FM tone example, showing the shape of the SET transform and the maximum absolute value.

```text
Te shape (201, 401)   |Te| max 0.932368651482803

```

--------------------------------

### OSD.preset

Source: https://pysdkit.readthedocs.io/en/latest/API/pysdkit._osd.html

Create an OSD instance with a predefined component list for common demos.

```APIDOC
## OSD.preset(name, length, **overrides)

### Description
Build a ready-made component list for common demos. The preset name selects a predefined configuration, and the length parameter scales default weights.

### Method
preset

### Parameters
- **name** (str) - Required - Preset name: "convex_demo", "l1_trend", or "nonconvex_square".
- **length** (int) - Required - Signal length T used to scale default weights.
- **overrides** (kwargs) - Optional - Additional overrides for component parameters.

### Returns
- **OSD** - An OSD instance with the preset component list.
```

--------------------------------

### Output of concrete two-tone example

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/vmd/vmd.html

Shows the printed output from the concrete two-tone example: estimated normalized center frequencies, approximate Hz, and relative errors for each mode.

```text
Estimated normalized center frequencies: [0.024 0.096]
Approx. Hz: [24. 96.]
mode0 RE = 0.008418452431093426
mode1 RE = 0.02589274980252264
```

--------------------------------

### Initialize and use BA_ACMD

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/b173dc3aa47b1b79dce24d7ebc4a9c79/ba_acmd.ipynb

Demonstrates importing BA_ACMD, generating a demo signal, and performing signal decomposition using fit_transform.

```python
from pysdkit import BA_ACMD
from pysdkit._acmd.ba_acmd import generate_demo_signal

t, x, snr, comps = generate_demo_signal(fs=5000, noise_std=0.2)
ba = BA_ACMD(fs=5000, beta=1e-10, tol=1e-7, ce=0.3,
             offset=0.01, cut_pfreq=0.0015)
modes = ba.fit_transform(x)                 # (K, N)
modes, IFs, IAs = ba.fit_transform(x, return_all=True)
```

--------------------------------

### Example output of VGNMD decomposition

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/gdmd/vgnmd.html

Shows the printed output from the VGNMD fit_transform example, including the number of modes, type array, reconstruction error, and best correlation matches.

```text
extracted modes: (7, 3000)
types (1=chirp, 2=dispersive): [1 1 1 2 2 2 2]
reconstruction relative error: 0.10203804312926644

Best |corr| vs each true mode:
  true m1 -> est m3 (chirp), |corr| = 0.997
  true m2 -> est m2 (chirp), |corr| = 0.995
  true m3 -> est m1 (chirp), |corr| = 0.995
  true m4 -> est m4 (dispersive), |corr| = 0.990
  true m5 -> est m5 (dispersive), |corr| = 0.999
  true m6 -> est m6 (dispersive), |corr| = 0.984
  true m7 -> est m7 (dispersive), |corr| = 0.997
```

--------------------------------

### SEMD API summary showing initialization, transform, and reconstruction

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/23873c55810fadaf50ce08ea0cccdf36/semd.ipynb

Shows the core init, fit_transform, and reconstruct methods for SEMD construction and usage. It highlights the parameter options to specify the number of intervals or an interval ratio and the dimensional relationship between input signal and the produced IMFs.

```python
from pysdkit import SEMD

semd = SEMD(num_interval=50, max_imfs=4)   # or interval_ratio=0.2
IMFs = semd.fit_transform(signal)          # signal: (N, M)
# IMFs shape: (K, M, N)
y_hat = semd.reconstruct()
```

--------------------------------

### Perform HHT Analysis with PySDKit

Source: https://pysdkit.readthedocs.io/en/latest/_downloads/d2d317e0cc3e0132b393650fe7bd5aee/hht.ipynb

A concise example demonstrating the HHT pipeline: generating test data, decomposing the signal into IMFs, and plotting the resulting Hilbert spectrum.

```python
from pysdkit import HHT
from pysdkit.data import test_hht

t, x = test_hht()
hht = HHT(max_imfs=4)
imfs, env, freq = hht.fit_transform(x, fs=1000, return_all=True)
hht.plot_spectrum(freq_lim=(0, 80))
```

--------------------------------

### Example output for NS-TEMD and EMD comparison

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/emd_variants/nstemd.html

Console output showing the IMF shapes, reconstruction error, PCA eigenvalues, and IMF counts for the comparison script.

```text
NS-TEMD IMFs (3, 400, 3) recon max abs error 2.220446049250313e-16
PCA eigenvalues [58.6855  0.2144  0.0626]
per-channel EMD IMF counts [4, 5, 5]
```

--------------------------------

### Import VME and example generators

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/vmd/vme.html

Imports numpy, matplotlib, and the VME class and functions from pysdkit, including example generators and ECG data loader. Also prints the VME() object.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit import VME, vme
from pysdkit._vmd.vme import (
    generate_vme_example1,
    generate_vme_example2,
    generate_vme_example3a,
    generate_vme_example3b,
    load_vme_ecg_055m,
)

print(VME())

```

```text
Variational Mode Extraction (VME)

```

--------------------------------

### Import required libraries and IMCKD functions

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/deconvolution/imckd.html

Imports numpy, matplotlib, and the necessary pysdkit functions for the IMCKD example. This includes load_imckd_sig1 for loading the sample signal, and utility functions for envelope spectrum, IMCKD, and kurtosis calculations.

```python
import numpy as np
import matplotlib.pyplot as plt

from pysdkit.data import load_imckd_sig1
from pysdkit.utils import (
    annotate_harmonics,
    envelope_spectrum,
    imckd,
    matlab_kurtosis,
    peak_frequency,
)

```

--------------------------------

### ATFFC cluster count output

Source: https://pysdkit.readthedocs.io/en/latest/auto_examples/gdmd/vgnmd.html

Shows the printed output from the ATFFC cluster visualization example.

```text
ATFFC returned 7 clusters
```