@danielsimonjr/mathts-functions 0.32.0 → 0.34.0

package/dist/numbertheory/extra.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Number-theory fills — closes gaps left by the existing combinatorics/number-theory
+ * surface (`typed/combinatorics.ts`): continued fractions, Euler numbers, the signed
+ * Stirling numbers of the first kind, discrete logarithm (BSGS), primitive roots,
+ * multiplicative order, the Kronecker symbol, and lexicographic
+ * permutation/combination *enumerators* (the existing `permutations`/`combinations`
+ * only return counts, not the tuples themselves).
+ *
+ * Plain exported functions (not `mathTyped` dispatch) — all take/return `number`
+ * or generic arrays, matching the style of `descriptive-stats.ts`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Simple continued fraction expansion `[a0, a1, a2, ...]` of `x`, where
+ * `a_i = floor(r)` and `r <- 1 / (r - a_i)`.
+ *
+ * Stops after `maxTerms` (default 20) or once the fractional part is smaller
+ * than `1e-12` (the remaining value is effectively an integer).
+ *
+ * @param x - The number to expand
+ * @param maxTerms - Maximum number of terms to compute (default 20)
+ * @returns The sequence of partial-quotient terms
+ *
+ * @example
+ * continuedFraction(3.245, 5) // => [3, 4, 12, 4, ...]
+ */
+export declare function continuedFraction(x: number, maxTerms?: number): number[];
+/**
+ * Euler numbers `E_0..E_n` (the coefficients in the secant Maclaurin series).
+ *
+ * `E_0 = 1`; all odd-index Euler numbers are 0; for even `m > 0`:
+ * `E_m = -sum_{k=0}^{m/2-1} C(m, 2k) * E_{2k}`.
+ *
+ * @param n - Non-negative integer: compute E_0 through E_n
+ * @returns Array of length `n + 1`: `[E_0, E_1, ..., E_n]`
+ *
+ * @example
+ * eulerNumbers(6) // => [1, 0, -1, 0, 5, 0, -61]
+ */
+export declare function eulerNumbers(n: number): number[];
+/**
+ * Signed Stirling number of the first kind `s(n, k)`.
+ *
+ * Recurrence: `s(n, k) = s(n-1, k-1) - (n-1)*s(n-1, k)`, with `s(0, 0) = 1`
+ * and `s(n, 0) = 0` for `n > 0`.
+ *
+ * @param n - Non-negative integer
+ * @param k - Non-negative integer, `0 <= k <= n`
+ * @returns The signed Stirling number `s(n, k)`
+ *
+ * @example
+ * stirlingS1(5, 2) // => -50
+ */
+export declare function stirlingS1(n: number, k: number): number;
+/**
+ * Discrete logarithm via baby-step giant-step: the smallest `x >= 0` such
+ * that `g^x === h (mod p)`, or `-1` if none exists within `[0, p-1]`.
+ *
+ * Uses `BigInt` internally for modular exponentiation/inversion to avoid
+ * overflow. `m = ceil(sqrt(p-1))` baby steps are stored in a map; the giant
+ * steps multiply by `g^(-m) mod p` each round.
+ *
+ * @param g - Base
+ * @param h - Target
+ * @param p - Prime modulus
+ * @returns The smallest non-negative `x` with `g^x === h (mod p)`, or `-1`
+ *
+ * @example
+ * discreteLog(2, 3, 5) // => 3   (2^3 = 8 === 3 mod 5)
+ */
+export declare function discreteLog(g: number, h: number, p: number): number;
+/**
+ * Smallest primitive root modulo a prime `p`.
+ *
+ * For each candidate `g = 2, 3, ...`, `g` is a primitive root iff
+ * `g^((p-1)/q) !== 1 (mod p)` for every prime factor `q` of `p - 1`.
+ *
+ * @param p - An odd prime (p = 2 returns 1 trivially)
+ * @returns The smallest primitive root modulo p
+ *
+ * @example
+ * primitiveRoot(7) // => 3
+ */
+export declare function primitiveRoot(p: number): number;
+/**
+ * Multiplicative order of `a` modulo `n`: the smallest `k > 0` with
+ * `a^k === 1 (mod n)`. Returns `-1` if `gcd(a, n) !== 1` (no order exists).
+ *
+ * @param a - Integer
+ * @param n - Positive integer modulus
+ * @returns The multiplicative order, or -1 if undefined
+ *
+ * @example
+ * multiplicativeOrder(2, 7) // => 3
+ */
+export declare function multiplicativeOrder(a: number, n: number): number;
+/**
+ * Kronecker symbol `(a|n)`, generalizing the Jacobi symbol `(a|n)` (odd
+ * positive `n`) to all integers `n`.
+ *
+ * - `(a|0) = 1` if `|a| = 1`, else `0`.
+ * - Sign of `n` is extracted first: `(a|-1) = -1` if `a < 0`, else `1`.
+ * - Factors of 2 are extracted from `n` using `(a|2)`: `0` if `a` even,
+ *   `1` if `a === ±1 (mod 8)`, `-1` if `a === ±3 (mod 8)`.
+ * - The remaining odd part is evaluated via the standard Jacobi reciprocity
+ *   recursion.
+ *
+ * @param a - Integer
+ * @param n - Integer
+ * @returns -1, 0, or 1
+ *
+ * @example
+ * kroneckerSymbol(2, 3) // => -1
+ */
+export declare function kroneckerSymbol(a: number, n: number): number;
+/**
+ * Enumerate all length-`k` combinations of `arr` (index-order subsequences,
+ * i.e. lexicographic order for a sorted input) as an array of tuples.
+ *
+ * @param arr - Source array
+ * @param k - Combination length
+ * @returns All `C(arr.length, k)` combinations, in lexicographic order
+ *
+ * @example
+ * combinationsGen([1, 2, 3], 2) // => [[1,2],[1,3],[2,3]]
+ */
+export declare function combinationsGen<T>(arr: readonly T[], k: number): T[][];
+/**
+ * Enumerate all length-`k` permutations (ordered arrangements) of `arr`
+ * as an array of tuples, in lexicographic order of index selection.
+ * `k` defaults to `arr.length` (full permutations).
+ *
+ * @param arr - Source array
+ * @param k - Permutation length (default: `arr.length`)
+ * @returns All `n! / (n-k)!` permutations, in lexicographic order
+ *
+ * @example
+ * permutationsGen([1, 2, 3], 2) // => 6 tuples: [1,2],[1,3],[2,1],[2,3],[3,1],[3,2]
+ */
+export declare function permutationsGen<T>(arr: readonly T[], k?: number): T[][];
+//# sourceMappingURL=extra.d.ts.map

package/dist/numbertheory/extra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra.d.ts","sourceRoot":"","sources":["../../src/numbertheory/extra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,EAAE,CAcpE;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBhD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAevD;AAqCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA+BnE;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB/C;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAehE;AAaD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA0C5D;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAoBtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,GAAE,MAAmB,GAAG,CAAC,EAAE,EAAE,CAwBnF"}

package/dist/numeric/gauss-nodes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Gauss-Legendre quadrature nodes and weights.
+ *
+ * `rootsLegendre(n)` finds the n roots of the degree-n Legendre polynomial
+ * P_n via Newton's method (initial guess from the standard asymptotic
+ * approximation), then derives the corresponding quadrature weights. This is
+ * the classical fixed-node table underlying Gauss-Legendre quadrature on
+ * [-1, 1]; callers needing a custom node count (rather than the library's
+ * built-in fixed-order `integrate`/`gaussLegendre` routines) use this
+ * directly.
+ *
+ * @packageDocumentation
+ */
+/** Result of {@link rootsLegendre}: nodes ascending on [-1, 1] with matching weights. */
+export interface RootsLegendreResult {
+    nodes: number[];
+    weights: number[];
+}
+/**
+ * n-point Gauss-Legendre quadrature nodes and weights on [-1, 1].
+ *
+ * Nodes are the roots of the degree-n Legendre polynomial P_n, refined by
+ * Newton's method from the standard asymptotic initial guess
+ * `cos(pi*(i+0.75)/(n+0.5))`. Weights are `2 / ((1-x_i^2) * P'_n(x_i)^2)`.
+ *
+ * @param n - Number of quadrature points (positive integer)
+ * @returns Nodes (ascending) and matching weights
+ *
+ * @example
+ * rootsLegendre(3)
+ * // { nodes: [-0.7745966692, 0, 0.7745966692],
+ * //   weights: [0.5555555556, 0.8888888889, 0.5555555556] }
+ */
+export declare function rootsLegendre(n: number): RootsLegendreResult;
+//# sourceMappingURL=gauss-nodes.d.ts.map

package/dist/numeric/gauss-nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gauss-nodes.d.ts","sourceRoot":"","sources":["../../src/numeric/gauss-nodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,yFAAyF;AACzF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAuBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,mBAAmB,CA+B5D"}

package/dist/signal/conv.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Convolution Operations
+ *
+ * Implements 1D and 2D convolution using both direct and FFT methods.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Convolution mode - determines output size
+ */
+export type ConvMode = 'full' | 'same' | 'valid';
+/**
+ * Direct 1D convolution (for small inputs)
+ *
+ * @param x - Input signal
+ * @param h - Convolution kernel
+ * @param mode - Output mode: 'full', 'same', or 'valid'
+ * @returns Convolution result
+ */
+export declare function convDirect(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * FFT-based 1D convolution (efficient for large inputs)
+ *
+ * Uses the convolution theorem: conv(x,h) = IFFT(FFT(x) * FFT(h))
+ *
+ * @param x - Input signal
+ * @param h - Convolution kernel
+ * @param mode - Output mode: 'full', 'same', or 'valid'
+ * @returns Convolution result
+ */
+export declare function convFFT(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * 1D Convolution with automatic method selection
+ *
+ * Automatically selects direct or FFT method based on input sizes.
+ *
+ * @param x - Input signal
+ * @param h - Convolution kernel
+ * @param mode - Output mode: 'full' (default), 'same', or 'valid'
+ * @returns Convolution result
+ *
+ * @example
+ * ```typescript
+ * // Simple convolution
+ * const signal = [1, 2, 3, 4, 5];
+ * const kernel = [1, 0, -1]; // Edge detection
+ * const result = conv(signal, kernel, 'same');
+ * ```
+ */
+export declare function conv(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * Cross-correlation of two signals
+ *
+ * Cross-correlation is convolution with the kernel reversed.
+ *
+ * @param x - First signal
+ * @param h - Second signal
+ * @param mode - Output mode
+ * @returns Cross-correlation result
+ */
+export declare function xcorr(x: number[] | Float64Array, h: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * Auto-correlation of a signal
+ *
+ * @param x - Input signal
+ * @param mode - Output mode
+ * @returns Auto-correlation result
+ */
+export declare function autocorr(x: number[] | Float64Array, mode?: ConvMode): number[];
+/**
+ * Direct 2D convolution
+ *
+ * @param image - 2D input array
+ * @param kernel - 2D convolution kernel
+ * @param mode - Output mode
+ * @returns 2D convolution result
+ */
+export declare function conv2Direct(image: number[][], kernel: number[][], mode?: ConvMode): number[][];
+/**
+ * FFT-based 2D convolution
+ *
+ * @param image - 2D input array
+ * @param kernel - 2D convolution kernel
+ * @param mode - Output mode
+ * @returns 2D convolution result
+ */
+export declare function conv2FFT(image: number[][], kernel: number[][], mode?: ConvMode): number[][];
+/**
+ * 2D Convolution with automatic method selection
+ *
+ * @param image - 2D input array
+ * @param kernel - 2D convolution kernel
+ * @param mode - Output mode: 'full' (default), 'same', or 'valid'
+ * @returns 2D convolution result
+ *
+ * @example
+ * ```typescript
+ * // Edge detection with Sobel kernel
+ * const image = [
+ *   [1, 2, 3],
+ *   [4, 5, 6],
+ *   [7, 8, 9],
+ * ];
+ * const sobelX = [
+ *   [-1, 0, 1],
+ *   [-2, 0, 2],
+ *   [-1, 0, 1],
+ * ];
+ * const edges = conv2(image, sobelX, 'same');
+ * ```
+ */
+export declare function conv2(image: number[][], kernel: number[][], mode?: ConvMode): number[][];
+//# sourceMappingURL=conv.d.ts.map

package/dist/signal/conv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conv.d.ts","sourceRoot":"","sources":["../../src/signal/conv.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAYjD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CA8CV;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CAsDV;AAOD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAClB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CAWV;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAC1B,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,CAKV;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,IAAI,GAAE,QAAiB,GAAG,MAAM,EAAE,CAEtF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,MAAM,EAAE,MAAM,EAAE,EAAE,EAClB,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,EAAE,CA8DZ;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,MAAM,EAAE,MAAM,EAAE,EAAE,EAClB,IAAI,GAAE,QAAiB,GACtB,MAAM,EAAE,EAAE,CAiGZ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,GAAE,QAAiB,GAAG,MAAM,EAAE,EAAE,CAgBhG"}

package/dist/signal/fft-helpers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Real FFT: compute the full FFT of a real signal and keep only the first
+ * `floor(n/2)+1` bins — the non-redundant half of the conjugate-symmetric spectrum.
+ *
+ * @param x Real input signal
+ * @returns `{ re, im }` arrays of length `floor(n/2)+1`
+ */
+export declare function rfft(x: number[]): {
+    re: number[];
+    im: number[];
+};
+/**
+ * Inverse real FFT: reconstruct the full conjugate-symmetric spectrum of length `n`
+ * from the non-redundant half produced by {@link rfft} (bins `n/2+1..n-1` are the
+ * conjugates of bins `n/2-1..1`), inverse-FFT it, and return the real parts.
+ *
+ * @param spec `{ re, im }` half-spectrum (bins `0..floor(n/2)`)
+ * @param n Length of the reconstructed real signal
+ * @returns Real-valued signal of length `n`
+ */
+export declare function irfft(spec: {
+    re: number[];
+    im: number[];
+}, n: number): number[];
+/**
+ * Shift the zero-frequency component to the center of the spectrum (roll by `floor(n/2)`).
+ */
+export declare function fftshift(x: number[]): number[];
+/**
+ * Inverse of {@link fftshift} (roll by `ceil(n/2)`).
+ */
+export declare function ifftshift(x: number[]): number[];
+/**
+ * DFT sample frequencies: `[0, 1, ..., ceil(n/2)-1, -floor(n/2), ..., -1] / (n*d)`.
+ *
+ * @param n Number of samples
+ * @param d Sample spacing (default 1)
+ */
+export declare function fftfreq(n: number, d?: number): number[];
+/**
+ * DFT sample frequencies matching {@link rfft} output: `[0, 1, ..., floor(n/2)] / (n*d)`.
+ *
+ * @param n Number of samples
+ * @param d Sample spacing (default 1)
+ */
+export declare function rfftfreq(n: number, d?: number): number[];
+/**
+ * 2-D FFT: FFT each row, then FFT each column of the result. Delegates directly to
+ * the package's N-dimensional `fft`, which already performs exactly this row-then-
+ * column transform when given a 2-D array.
+ */
+export declare function fftn(x: number[][]): {
+    re: number[][];
+    im: number[][];
+};
+//# sourceMappingURL=fft-helpers.d.ts.map

package/dist/signal/fft-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fft-helpers.d.ts","sourceRoot":"","sources":["../../src/signal/fft-helpers.ts"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG;IAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,CAYhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAY/E;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI/C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,MAAM,EAAE,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,MAAM,EAAE,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG;IAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CAKtE"}

package/dist/signal/fft.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Fast Fourier Transform (FFT)
+ *
+ * Implements the Cooley-Tukey radix-2 decimation-in-time FFT algorithm.
+ * For non-power-of-2 lengths, zero-pads to next power of 2.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Complex number representation for FFT
+ */
+export interface ComplexNumber {
+    re: number;
+    im: number;
+}
+/**
+ * FFT result containing the frequency spectrum
+ */
+export interface FFTResult {
+    /** Complex frequency components */
+    spectrum: ComplexNumber[];
+    /** Original signal length before padding */
+    originalLength: number;
+    /** Padded length (power of 2) */
+    paddedLength: number;
+}
+/**
+ * Create a complex number
+ */
+export declare function complex(re: number, im?: number): ComplexNumber;
+/**
+ * Complex conjugate
+ */
+export declare function complexConj(a: ComplexNumber): ComplexNumber;
+/**
+ * Complex magnitude
+ */
+export declare function complexAbs(a: ComplexNumber): number;
+/**
+ * Complex phase/argument
+ */
+export declare function complexArg(a: ComplexNumber): number;
+/**
+ * Compute the Fast Fourier Transform of a real or complex signal.
+ *
+ * Uses the Cooley-Tukey radix-2 decimation-in-time algorithm.
+ * Input is zero-padded to the next power of 2 if necessary.
+ *
+ * @param signal - Input signal (real numbers or complex numbers)
+ * @returns FFT result with spectrum and length info
+ *
+ * @example
+ * ```typescript
+ * // FFT of a real signal
+ * const signal = [1, 0, -1, 0];
+ * const result = fft(signal);
+ * console.log(result.spectrum); // Frequency components
+ *
+ * // FFT of a complex signal
+ * const complexSignal = [
+ *   { re: 1, im: 0 },
+ *   { re: 0, im: 1 },
+ * ];
+ * const result2 = fft(complexSignal);
+ * ```
+ */
+export declare function fft(signal: number[] | Float64Array | ComplexNumber[]): FFTResult;
+/**
+ * Compute the Inverse Fast Fourier Transform.
+ *
+ * Recovers the time-domain signal from its frequency spectrum.
+ *
+ * @param spectrum - Complex frequency spectrum
+ * @param originalLength - Optional: truncate result to this length
+ * @returns Recovered signal
+ *
+ * @example
+ * ```typescript
+ * // Round-trip test
+ * const signal = [1, 2, 3, 4];
+ * const result = fft(signal);
+ * const recovered = ifft(result.spectrum, result.originalLength);
+ * // recovered ≈ signal
+ * ```
+ */
+export declare function ifft(spectrum: ComplexNumber[], originalLength?: number): ComplexNumber[];
+/**
+ * Compute the real part of IFFT result
+ */
+export declare function ifftReal(spectrum: ComplexNumber[], originalLength?: number): number[];
+/**
+ * Compute the magnitude spectrum (|X(k)|)
+ */
+export declare function fftMagnitude(spectrum: ComplexNumber[]): number[];
+/**
+ * Compute the power spectrum (|X(k)|²)
+ */
+export declare function fftPower(spectrum: ComplexNumber[]): number[];
+/**
+ * Compute the phase spectrum (arg(X(k)))
+ */
+export declare function fftPhase(spectrum: ComplexNumber[]): number[];
+/**
+ * Compute FFT frequency bins for a given sample rate
+ *
+ * @param n - Number of FFT points
+ * @param sampleRate - Sample rate in Hz
+ * @returns Array of frequencies in Hz
+ */
+export declare function fftFrequencies(n: number, sampleRate?: number): number[];
+/**
+ * Compute the 2D FFT of a matrix
+ *
+ * @param matrix - 2D array of real or complex values
+ * @returns 2D frequency spectrum
+ */
+export declare function fft2(matrix: number[][] | ComplexNumber[][]): ComplexNumber[][];
+/**
+ * Compute the 2D inverse FFT
+ *
+ * @param spectrum - 2D frequency spectrum
+ * @returns 2D spatial domain result
+ */
+export declare function ifft2(spectrum: ComplexNumber[][]): ComplexNumber[][];
+/**
+ * Shift zero-frequency component to center of spectrum
+ *
+ * @param spectrum - FFT spectrum
+ * @returns Shifted spectrum
+ */
+export declare function fftshift<T>(spectrum: T[]): T[];
+/**
+ * Inverse of fftshift
+ */
+export declare function ifftshift<T>(spectrum: T[]): T[];
+//# sourceMappingURL=fft.d.ts.map

package/dist/signal/fft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fft.d.ts","sourceRoot":"","sources":["../../src/signal/fft.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,GAAG,aAAa,CAEjE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,aAAa,CAE3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnD;AA0DD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,aAAa,EAAE,GAAG,SAAS,CAqChF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAuBxF;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAGrF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAEhE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAE5D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,GAAE,MAAU,GAAG,MAAM,EAAE,CAa1E;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,CAoC9E;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,CA8BpE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAI9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAI/C"}

package/dist/signal/fir-smoothing.d.ts

@@ -0,0 +1,62 @@
+type Vec = readonly number[] | Float64Array;
+/** Polynomial/deconvolution division result: `signal = conv(divisor, quotient) + remainder`. */
+export interface DeconvolveResult {
+    quotient: number[];
+    remainder: number[];
+}
+/**
+ * FIR bandpass filter coefficients by the windowed-sinc method (Hamming
+ * window): `h[n] = (f2·sinc(f2·(n−M/2)) − f1·sinc(f1·(n−M/2)))·hamming[n]`,
+ * `M = numtaps−1`. `[f1, f2]` are cutoffs normalized to Nyquist (1 = Nyquist).
+ * This is the array-cutoff (bandpass) case the scalar-only `firwin` in
+ * `../signal-filter-extra.ts` didn't support (resolves the Phase-0 note).
+ */
+export declare function firwinBandpass(numtaps: number, cutoffs: readonly [number, number]): number[];
+/**
+ * Savitzky-Golay smoothing (`scipy.signal.savgol_filter`, default `mode='interp'`).
+ * For each interior position, fits a degree-`polyorder` polynomial (via the
+ * normal equations over a Vandermonde of the window offsets) to the centered
+ * `windowLength`-point window and takes the fitted value at the center. Edge
+ * points reuse the nearest full boundary window's fit, evaluated at the edge
+ * point's actual offset from that window's center (scipy's boundary handling).
+ * Exact on polynomials of degree <= `polyorder`.
+ */
+export declare function savgol(x: Vec, windowLength: number, polyorder: number): number[];
+/**
+ * FIR/polynomial deconvolution (`scipy.signal.deconvolve`): standard
+ * synthetic long division so that `signal = conv(divisor, quotient) + remainder`,
+ * with `quotient` of length `signal.length - divisor.length + 1` and
+ * `remainder` the same length as `signal` (zero when `divisor` exactly divides).
+ */
+export declare function deconvolve(signal: Vec, divisor: Vec): DeconvolveResult;
+/**
+ * Wiener adaptive filter (`scipy.signal.wiener`-style, per-sample noise
+ * estimate): local mean `m` and variance `v` over a sliding window of size
+ * `mysize` (same-length, zero-padded at the edges — matches `convDirect`'s
+ * `'same'` convention), noise power `= mean(v)`; output
+ * `m + max(0, v−noise)/max(v, noise)·(x−m)` (0 where both `v` and `noise` are 0).
+ */
+export declare function wiener(x: Vec, mysize?: number): number[];
+/**
+ * Least-squares linear-phase FIR design (`scipy.signal.firls`): `bands` is a
+ * flat list of `[lo, hi]` band-edge pairs (normalized to Nyquist, 1 = Nyquist)
+ * and `desired` the corresponding response values at those edges (linearly
+ * interpolated within each band; gaps between bands are unconstrained
+ * transition regions). Solves the normal equations of the cosine-basis
+ * representation of a symmetric (Type I odd-length / Type II even-length)
+ * linear-phase filter against a dense trapezoid-quadrature sampling of the
+ * specified bands, then maps the fitted basis coefficients back to taps.
+ */
+export declare function firls(numtaps: number, bands: readonly number[], desired: readonly number[]): number[];
+/**
+ * Parks-McClellan-style equiripple FIR design. **This is NOT the exact
+ * Remez-exchange algorithm** — it is Lawson's algorithm, an iteratively
+ * reweighted least squares (IRLS) scheme that approximates the minimax
+ * (Chebyshev) solution by repeatedly re-solving the `firls` normal equations
+ * with per-sample weights pushed up wherever the previous iteration's error
+ * was largest, converging toward (but not guaranteed to reach) a true
+ * equiripple response. Documented as approximate per the Task 3 spec.
+ */
+export declare function remez(numtaps: number, bands: readonly number[], desired: readonly number[]): number[];
+export {};
+//# sourceMappingURL=fir-smoothing.d.ts.map

package/dist/signal/fir-smoothing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fir-smoothing.d.ts","sourceRoot":"","sources":["../../src/signal/fir-smoothing.ts"],"names":[],"mappings":"AAUA,KAAK,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAG5C,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAsCD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAa5F;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BhF;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,GAAG,gBAAgB,CAiBtE;AAID;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,SAAI,GAAG,MAAM,EAAE,CAsBnD;AAoHD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAUV;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAkBV"}

package/dist/signal/iir-design.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Chebyshev I/II and elliptic (Cauer) IIR filter design, plus the supporting
+ * `zpk2sos`/`sosfilt`/`bilinear`/`buttord` utilities. Extends the Butterworth
+ * pipeline in `../signal-filter-extra.ts` with two more analog prototypes and
+ * reuses its shared zpk→transfer-function plumbing (`analogToDigital`,
+ * `polyFromRoots`). Matches `scipy.signal` — every coefficient set pinned
+ * against `scipy.signal.{cheby1,cheby2,ellip,bilinear,buttord}` (see
+ * `functions/tests/iir-design.test.ts`).
+ *
+ * The elliptic prototype (`ellipap`) follows Orfanidis, "Lecture Notes on
+ * Elliptic Filter Design" (the algorithm scipy itself implements): the filter
+ * degree equation is solved in closed form via the theta-function nome
+ * expansion (`ellipdeg`), and the "arc Jacobi sc" root (`arcJacSc1`) via the
+ * descending Landen transformation (`arcJacSn`) — no numerical optimizer is
+ * needed. Reuses the repo's existing AGM-based `ellipticKScalar` and
+ * `jacobiSN`/`jacobiCN`/`jacobiDN` (Phase 5 special functions, `m = k²`
+ * convention, matching scipy's `ellipk`/`ellipj`).
+ */
+import { Complex } from '@danielsimonjr/mathts-core';
+import { type FilterBtype } from '../signal-filter-extra.js';
+type Vec = readonly number[] | Float64Array;
+/**
+ * Chebyshev Type I digital IIR filter design — equiripple in the passband, `rp`
+ * dB of ripple. `Wn` is the cutoff (scalar) or `[low, high]` band edges,
+ * normalized to Nyquist. Matches `scipy.signal.cheby1(N, rp, Wn, btype)`.
+ */
+export declare function cheby1(N: number, rp: number, Wn: number | readonly number[], btype?: FilterBtype): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Chebyshev Type II digital IIR filter design — equiripple in the stopband,
+ * `rs` dB of stopband attenuation, monotone passband. `Wn` is the cutoff
+ * (scalar) or `[low, high]` band edges, normalized to Nyquist. Matches
+ * `scipy.signal.cheby2(N, rs, Wn, btype)`.
+ */
+export declare function cheby2(N: number, rs: number, Wn: number | readonly number[], btype?: FilterBtype): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Elliptic (Cauer) digital IIR filter design — equiripple in both passband
+ * (`rp` dB) and stopband (`rs` dB); the steepest roll-off of the four classical
+ * IIR families for a given order. `Wn` is the cutoff (scalar) or `[low, high]`
+ * band edges, normalized to Nyquist. Matches `scipy.signal.ellip(N, rp, rs, Wn,
+ * btype)` exactly (verified against `scipy.signal` 1.17.1 — see
+ * `functions/tests/iir-design.test.ts`); this is a full port of scipy's
+ * closed-form (nome-based) elliptic design, not an approximation.
+ */
+export declare function ellip(N: number, rp: number, rs: number, Wn: number | readonly number[], btype?: FilterBtype): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Analog-to-digital bilinear (Tustin) transform of a transfer function: given
+ * `H(s) = b(s)/a(s)` (coefficients highest-degree-first), substitutes
+ * `s = 2·fs·(z−1)/(z+1)` to produce the digital `{ b, a }` (no pre-warping is
+ * done — the caller pre-warps `fs`/critical frequencies if needed). Matches
+ * `scipy.signal.bilinear(b, a, fs)`.
+ */
+export declare function bilinear(bIn: Vec, aIn: Vec, fs: number): {
+    b: number[];
+    a: number[];
+};
+/**
+ * Minimum Butterworth filter order (and the corresponding `-3dB`-ish natural
+ * frequency `Wn`) meeting a passband/stopband spec, for a digital lowpass
+ * (`wp < ws`) or highpass (`wp > ws`) filter. `wp`/`ws` are normalized to
+ * Nyquist (0..1); `gpass`/`gstop` are in dB. Matches
+ * `scipy.signal.buttord(wp, ws, gpass, gstop)` (scalar/digital case only —
+ * the bandpass/bandstop array form is not implemented).
+ */
+export declare function buttord(wp: number, ws: number, gpass: number, gstop: number): {
+    N: number;
+    Wn: number;
+};
+type ZpkRoot = number | Complex;
+/**
+ * Group zeros/poles/gain into cascaded second-order sections:
+ * `[[b0,b1,b2,a0,a1,a2], …]`, each a monic-denominator biquad (`a0 = 1`) with
+ * the overall gain folded into the first section's numerator. `z` is
+ * zero-padded (roots at the origin) if shorter than `p`. Matches
+ * `scipy.signal.zpk2sos` in effect (the two decompositions can differ in
+ * pairing order, but the resulting cascaded transfer function is identical).
+ */
+export declare function zpk2sos(z: readonly ZpkRoot[], p: readonly ZpkRoot[], k: number): number[][];
+/**
+ * Apply a cascade of second-order sections (`[[b0,b1,b2,a0,a1,a2], …]`, as
+ * produced by `zpk2sos`) to `x`, each biquad in direct-form-II transposed.
+ * Matches `scipy.signal.sosfilt(sos, x)`.
+ */
+export declare function sosfilt(sos: readonly (readonly number[])[], x: Vec): number[];
+export {};
+//# sourceMappingURL=iir-design.d.ts.map

package/dist/signal/iir-design.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iir-design.d.ts","sourceRoot":"","sources":["../../src/signal/iir-design.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAKnC,KAAK,GAAG,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC;AAoB5C;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAI9B;AAgCD;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAI9B;AAkJD;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAC9B,KAAK,GAAE,WAAmB,GACzB;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAK9B;AA4BD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CA8BrF;AAID;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAc3B;AAID,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAoDhC;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAmB3F;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAS7E"}