feat: initial release

Assisted-by: GLM 5.3 Flash

signal/waveletdwt.go

@@ -0,0 +1,323 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+package signal
+
+import (
+	"slices"
+
+	"sourcedock.dev/petrbalvin/tensor/internal/base"
+	"sourcedock.dev/petrbalvin/tensor/internal/core"
+)
+
+// Daubechies discrete wavelets: db2 through db8 beside the
+// Haar transform the package already carries in DWT and IDWT. Each
+// family is an orthonormal two-channel filter bank driven over levels
+// of halving blocks, packed in the same [A_L, D_L, …, D_1] layout the
+// Haar transform uses; each dbN pair has N vanishing moments and 2N
+// taps, so higher families resolve smoother signals into sparser
+// details but tie the boundary condition to longer blocks.
+//
+// The tables below are not trusted on authority: they were produced
+// by the spectral factorisation of Daubechies' polynomial
+// P(y) = Σ_k C(N−1+k, k)·y^k, and the tests certify them against the
+// defining conditions, the unit norm, the shift-2 orthogonality, the
+// N vanishing moments and the spectral identity
+// |H(ω)|² = 2·cos^{2N}(ω/2)·P(sin²(ω/2)), so a mistyped digit cannot
+// survive.
+
+// Daubechies names a member of the Daubechies wavelet family: dbN
+// carries N vanishing moments and a 2N-tap filter pair. Haar remains
+// the db1 case and keeps its own exact transform in DWT and IDWT.
+type Daubechies string
+
+const (
+	// DB2 is the 4-tap Daubechies wavelet with 2 vanishing moments.
+	DB2 Daubechies = "db2"
+	// DB3 is the 6-tap Daubechies wavelet with 3 vanishing moments.
+	DB3 Daubechies = "db3"
+	// DB4 is the 8-tap Daubechies wavelet with 4 vanishing moments.
+	DB4 Daubechies = "db4"
+	// DB5 is the 10-tap Daubechies wavelet with 5 vanishing moments.
+	DB5 Daubechies = "db5"
+	// DB6 is the 12-tap Daubechies wavelet with 6 vanishing moments.
+	DB6 Daubechies = "db6"
+	// DB7 is the 14-tap Daubechies wavelet with 7 vanishing moments.
+	DB7 Daubechies = "db7"
+	// DB8 is the 16-tap Daubechies wavelet with 8 vanishing moments.
+	DB8 Daubechies = "db8"
+)
+
+// The scaling filters h, the low-pass analysis side, normalised to
+// Σ h = √2. Treat them as read-only.
+var (
+	db2Coeffs = []float64{
+		0.48296291314453421, 0.83651630373780794, 0.22414386804201339, -0.1294095225512604,
+	}
+	db3Coeffs = []float64{
+		0.33267055295008258, 0.80689150931109266, 0.45987750211849149, -0.13501102001025453,
+		-0.085441273882026644, 0.035226291885709533,
+	}
+	db4Coeffs = []float64{
+		0.23037781330889651, 0.71484657055291556, 0.63088076792985903, -0.027983769416859948,
+		-0.18703481171909306, 0.030841381835560764, 0.032883011666885203, -0.010597401785069032,
+	}
+	db5Coeffs = []float64{
+		0.1601023979741929, 0.60382926979718965, 0.72430852843777283, 0.13842814590132091,
+		-0.24229488706638203, -0.032244869584638361, 0.077571493840045691, -0.0062414902127982726,
+		-0.012580751999081997, 0.0033357252854737704,
+	}
+	db6Coeffs = []float64{
+		0.11154074335010949, 0.49462389039845328, 0.75113390802109559, 0.31525035170919741,
+		-0.22626469396543983, -0.12976686756726177, 0.097501605587322904, 0.027522865530305803,
+		-0.031582039317486044, 0.00055384220116149461, 0.0047772575109455116, -0.0010773010853084798,
+	}
+	db7Coeffs = []float64{
+		0.07785205408500917, 0.39653931948191723, 0.72913209084623509, 0.46978228740519357,
+		-0.14390600392856487, -0.22403618499387515, 0.071309219266830329, 0.080612609151083051,
+		-0.0380299369350144, -0.016574541630666881, 0.012550998556099839, 0.00042957797292136738,
+		-0.0018016407040474906, 0.00035371379997452024,
+	}
+	db8Coeffs = []float64{
+		0.054415842243104001, 0.3128715909143, 0.67563073629728954, 0.58535468365420718,
+		-0.015829105256349327, -0.28401554296154741, 0.00047248457391386436, 0.12874742662047808,
+		-0.017369301001807447, -0.044088253930794685, 0.013981027917398216, 0.0087460940474057974,
+		-0.0048703529934515776, -0.00039174037337694672, 0.00067544940645056933, -0.00011747678412476953,
+	}
+)
+
+// daubechiesTaps resolves a family name to its scaling filter.
+func daubechiesTaps(name string, family Daubechies) ([]float64, error) {
+	switch family {
+	case DB2:
+		return db2Coeffs, nil
+	case DB3:
+		return db3Coeffs, nil
+	case DB4:
+		return db4Coeffs, nil
+	case DB5:
+		return db5Coeffs, nil
+	case DB6:
+		return db6Coeffs, nil
+	case DB7:
+		return db7Coeffs, nil
+	case DB8:
+		return db8Coeffs, nil
+	default:
+		return nil, base.Errf("%s: unknown Daubechies family %q (want db2 through db8)", name, string(family))
+	}
+}
+
+// DWTMode picks the boundary treatment of the Daubechies transform.
+type DWTMode int
+
+const (
+	// DWTPeriodic treats the signal as one period of a periodic
+	// sequence: the default. Every block keeps its exact energy and
+	// the length must offer every level a multiple of the filter
+	// length to work on.
+	DWTPeriodic DWTMode = iota
+	// DWTZeroPad extends the signal with zeros at the tail to the
+	// next length the level tree needs, so any length transforms;
+	// the coefficients past the signal's own span carry the
+	// response of the step to zero at the seam.
+	DWTZeroPad
+)
+
+// DaubechiesDWT returns the discrete Daubechies wavelet transform of
+// the rank-1 real signal x over levels scales, packed as
+// [A_levels, D_levels, …, D_1]: the deepest approximation first, each
+// detail band after it, the finest last. mode picks the boundary
+// treatment, DWTPeriodic by default: it refuses a length that does
+// not leave every live block a multiple of the 2N-tap filter (the
+// deepest block must hold at least one filter length), while
+// DWTZeroPad zero-pads the tail to the next such length first. The
+// periodic transform conserves energy exactly; a zero-padded one
+// conserves the energy of the padded signal. levels must be at
+// least 1.
+func DaubechiesDWT(x *core.Array, family Daubechies, levels int, mode DWTMode) (*core.Array, error) {
+	const name = "DaubechiesDWT"
+	src, h, levels, mode, err := dwtPrepare(name, x, family, levels, mode)
+	if err != nil {
+		return nil, err
+	}
+	L := len(h)
+	n := x.Len()
+	// The periodic contract gates the length; the zero-padded one
+	// extends the tail to the smallest length that offers every
+	// level a multiple of the filter length instead.
+	length := n
+	if mode == DWTPeriodic {
+		if err := dwtLengthGate(name, n, L, levels); err != nil {
+			return nil, err
+		}
+	} else {
+		// The padded block must stay inside the allocator's reach: the
+		// shift wraps past the addressable range first, and a span that
+		// survives the wrap but tops the makeslice ceiling of 2^45
+		// float64 elements panics in the make below instead of refusing
+		// here.
+		span := L << (levels - 1)
+		if span <= 0 || span >= 1<<45 {
+			return nil, base.Errf("%s: %d levels need a padded length no machine could hold", name, levels)
+		}
+		length = ((n-1)/span + 1) * span
+	}
+	work := make([]float64, length)
+	copy(work, src)
+	g := daubechiesHighPass(h)
+	// Each pass halves the live block: the approximation and the
+	// detail land in scratch, then the block rearranges into
+	// [A, D] exactly as the packed layout wants.
+	scratch := make([]float64, length)
+	m := length
+	for range levels {
+		half := m / 2
+		a, d := scratch[:half], scratch[half:m]
+		dwtForwardLevel(work[:m], a, d, h, g)
+		copy(work[:half], a)
+		copy(work[half:m], d)
+		m = half
+	}
+	return core.FromFloats(work, length)
+}
+
+// DaubechiesIDWT inverts DaubechiesDWT over the same family, level
+// count and mode, undoing the packed layout deepest band first. The
+// coefficient vector must satisfy the length contract every forward
+// transform produced: a multiple of the filter length at every level
+// of the tree, whichever mode the forward ran. A zero-padded forward
+// transform therefore inverts to the padded length, whose head is
+// the original signal; the mode argument gates exactly this
+// contract, the inverse bank itself is the periodic one.
+func DaubechiesIDWT(coef *core.Array, family Daubechies, levels int, mode DWTMode) (*core.Array, error) {
+	const name = "DaubechiesIDWT"
+	src, h, levels, _, err := dwtPrepare(name, coef, family, levels, mode)
+	if err != nil {
+		return nil, err
+	}
+	if err := dwtLengthGate(name, coef.Len(), len(h), levels); err != nil {
+		return nil, err
+	}
+	g := daubechiesHighPass(h)
+	work := make([]float64, len(src))
+	copy(work, src)
+	m := len(work) >> levels
+	for range levels {
+		half := m
+		m = 2 * m
+		a := slices.Clone(work[:half])
+		d := slices.Clone(work[half:m])
+		for j := range m {
+			var av, dv float64
+			for k := range h {
+				// The synthesis taps land at even steps only:
+				// e/2 is the band index the tap reads.
+				e := j - k
+				if e < 0 {
+					e += m
+				}
+				if e&1 == 1 {
+					continue
+				}
+				av += h[k] * a[e>>1]
+				dv += g[k] * d[e>>1]
+			}
+			work[j] = av + dv
+		}
+	}
+	return core.FromFloats(work, len(work))
+}
+
+// dwtPrepare runs the shared contract of the Daubechies transforms
+// ahead of the length question: rank-1 real non-empty input, a known
+// family, at least one level, a known mode. It returns the widened
+// input, the scaling filter and the validated level count and mode.
+func dwtPrepare(name string, x *core.Array, family Daubechies, levels int, mode DWTMode) (src []float64, h []float64, levelsOut int, modeOut DWTMode, err error) {
+	if x.NDim() != 1 {
+		return nil, nil, 0, 0, base.Errf("%s: needs a rank-1 signal, got shape %s", name, base.ShapeText(x.Shape()))
+	}
+	if x.Dtype() == core.Complex {
+		return nil, nil, 0, 0, base.Errf("%s: complex signals are not supported", name)
+	}
+	if x.Len() == 0 {
+		return nil, nil, 0, 0, base.Errf("%s: an empty signal has no transform", name)
+	}
+	h, err = daubechiesTaps(name, family)
+	if err != nil {
+		return nil, nil, 0, 0, err
+	}
+	if levels < 1 {
+		return nil, nil, 0, 0, base.Errf("%s: levels must be at least 1, got %d", name, levels)
+	}
+	switch mode {
+	case DWTPeriodic, DWTZeroPad:
+	default:
+		return nil, nil, 0, 0, base.Errf("%s: unknown boundary mode %d", name, int(mode))
+	}
+	return widenFloats(x), h, levels, mode, nil
+}
+
+// dwtLengthGate enforces the tree contract on a length: the deepest
+// block, n>>levels−1 samples, must be a whole multiple of the filter
+// length and at least one filter long, which the halvings before it
+// then inherit. Shifts past the word width answer 0 and fail the
+// gate, which is exactly the refusal a too deep tree wants.
+func dwtLengthGate(name string, n, L, levels int) error {
+	blk := n >> (levels - 1)
+	if levels-1 >= 64 || (blk<<(levels-1)) != n || blk < L || blk%L != 0 {
+		return base.Errf("%s: %d levels need every live block to hold a multiple of the %d-tap filter, which %d samples do not offer",
+			name, levels, L, n)
+	}
+	return nil
+}
+
+// daubechiesHighPass derives the wavelet (high-pass) half of the bank
+// from the scaling filter: g[k] = (−1)^k·h[L−1−k].
+func daubechiesHighPass(h []float64) []float64 {
+	L := len(h)
+	g := make([]float64, L)
+	for k := range L {
+		sign := 1.0
+		if k%2 == 1 {
+			sign = -1
+		}
+		g[k] = sign * h[L-1-k]
+	}
+	return g
+}
+
+// dwtForwardLevel runs one periodic analysis level over the block
+// x of even length m: a[i] = Σ h[k]·x[(2i+k) mod m] and the same with
+// g for d. Outputs whose taps never wrap walk the block directly;
+// the ones near the block's end correct the few negative indices.
+func dwtForwardLevel(x, a, d, h, g []float64) {
+	m := len(x)
+	L := len(h)
+	half := m / 2
+	limit := (m - L) / 2
+	for i := 0; i <= limit; i++ {
+		base := 2 * i
+		var av, dv float64
+		for k := range L {
+			xv := x[base+k]
+			av += h[k] * xv
+			dv += g[k] * xv
+		}
+		a[i], d[i] = av, dv
+	}
+	for i := limit + 1; i < half; i++ {
+		base := 2*i - m
+		var av, dv float64
+		for k := range L {
+			idx := base + k
+			if idx < 0 {
+				idx += m
+			}
+			xv := x[idx]
+			av += h[k] * xv
+			dv += g[k] * xv
+		}
+		a[i], d[i] = av, dv
+	}
+}