tensor/signal/filterdesign.go

// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
// SPDX-License-Identifier: MIT

package signal

import (
	"math"
	"math/cmplx"
	"slices"

	"sourcedock.dev/petrbalvin/tensor/internal/base"
	"sourcedock.dev/petrbalvin/tensor/internal/core"
)

// IIR designs beyond the Butterworth pair: the Chebyshev equiripple
// family, the inverse Chebyshev, the elliptic (Cauer) designs, and
// the band shapes for every prototype. Each design walks the same
// road: an analog low-pass prototype at unit passband edge, the
// shape transformation of its pole-zero set with both band edges
// prewarped to the bilinear axis, and the bilinear mapping of each
// pole and zero. The mapping is exact, so the prototype's passband
// peak and edge attenuations land on the digital side at the mapped
// frequencies; that is what the tests pin.
//
// The coefficients come back in the same u = z⁻¹ convention as the
// Butterworth pair, with the denominator leading a one. Direct-form
// filtering loses digits as the order climbs, so past roughly order
// eight a design should be split into second-order sections by the
// caller; where that line sits is deliberately left to taste.

// prototype is one analog low-pass at unit passband edge. Poles and
// finite zeroes carry exact conjugate symmetry; the zeroes a low-pass
// holds at infinity are counted, not listed.
type prototype struct {
	poles           []complex128
	zeros           []complex128
	zerosAtInfinity int
	gain            float64
}

// chebyshev1 returns the type I prototype: the Butterworth circle
// squashed by the ripple's hyperbolic factor, so the passband swings
// between one and 1/sqrt(1+eps²), the peak normalised to one. The
// edge sits where the gain first drops to -rippleDB.
func chebyshev1(order int, rippleDB float64) prototype {
	eps := math.Sqrt(math.Pow(10, rippleDB/10) - 1)
	mu := math.Asinh(1/eps) / float64(order)
	poles := make([]complex128, 0, order)
	for k := range order {
		theta := math.Pi * float64(2*k+1) / float64(2*order)
		// One Sincos serves the pole's both factors: the pair is the
		// one the separate Sin and Cos calls produced, so the pole
		// keeps its bits.
		sinT, cosT := math.Sincos(theta)
		if math.Abs(cosT) < 1e-15 {
			// The odd order's real pole, built exactly.
			poles = append(poles, complex(-math.Sinh(mu), 0))
			continue
		}
		if cosT < 0 {
			continue // the mirror angle's conjugate, already stored
		}
		p := complex(-math.Sinh(mu)*sinT, math.Cosh(mu)*cosT)
		poles = append(poles, p, cmplx.Conj(p))
	}
	gain := 1.0
	if order%2 == 0 {
		gain = 1 / math.Sqrt(1+eps*eps)
	}
	return prototype{poles: poles, zerosAtInfinity: order, gain: gain}
}

// chebyshev2 returns the inverse Chebyshev: zeroes on the imaginary
// axis at the reciprocals of the type I ripple points, poles at the
// reciprocals of type I poles built with the stopband's factor, so
// the stopband floor is exactly the demanded attenuation. The root
// lattice runs over the integers of one parity between −(n−1) and
// n−1: for odd orders it passes through zero, holding the real pole
// there, and the zero at infinity keeps m = 0 out of the zero list.
func chebyshev2(order int, stopbandDB float64) prototype {
	de := 1 / math.Sqrt(math.Pow(10, stopbandDB/10)-1)
	mu := math.Asinh(1/de) / float64(order)
	poles := make([]complex128, 0, order)
	zeros := make([]complex128, 0, order)
	for m := -order + 1; m <= order-1; m += 2 {
		theta := math.Pi * float64(m) / float64(2*order)
		if m >= 0 {
			p := -1 / cmplx.Sinh(complex(mu, theta))
			if m == 0 {
				poles = append(poles, p)
			} else {
				poles = append(poles, p, cmplx.Conj(p))
			}
			if m > 0 {
				z := complex(0, 1/math.Sin(theta))
				zeros = append(zeros, z, cmplx.Conj(z))
			}
		}
	}
	return prototype{poles: poles, zeros: zeros,
		zerosAtInfinity: order - len(zeros), gain: 1}
}

// cauer returns the elliptic prototype. The zeroes are cd of the
// quarter-period fractions, read through the library's Jacobi
// functions; the poles ride the addition theorem through the
// amplitude v0 solved from the stopband's discrimination; and the
// degree equation closes through the nome, so ripple and attenuation
// both land on spec at the first transition edge.
func cauer(order int, rippleDB, stopbandDB float64) prototype {
	epsSq := math.Pow(10, rippleDB/10) - 1
	eps := math.Sqrt(epsSq)
	m1 := epsSq / (math.Pow(10, stopbandDB/10) - 1)
	m := ellipdeg(order, m1)
	capk := core.EllipticKScalar(m)

	// Amplitudes along the quarter period: u_j = j·K/n for odd j when
	// the order is even, even j when it is odd, where u = 0 holds the
	// zero at infinity.
	zeroes := make([]complex128, 0, order)
	amplitudes := make([][3]float64, 0, order)
	for j := 1 - order%2; j < order; j += 2 {
		u := float64(j) * capk / float64(order)
		s := jacobiScalar(core.JacobiSN, u, m)
		c := jacobiScalar(core.JacobiCN, u, m)
		d := jacobiScalar(core.JacobiDN, u, m)
		if math.Abs(s) > 1e-12 {
			z := complex(0, 1/(math.Sqrt(m)*s))
			zeroes = append(zeroes, z, cmplx.Conj(z))
		}
		amplitudes = append(amplitudes, [3]float64{s, c, d})
	}

	// v0: the amplitude solving sc(v0, 1−m1) = 1/ε on the
	// complementary parameter, through the identity sc(u, m) =
	// tan(am(u, m)): v0 = F(atan(1/ε), 1−m1), scaled by the nome
	// ratio the degree equation provides. The pole formula then reads
	// its Jacobi amplitudes at v0 on the prototype's own parameter.
	v0 := capk * core.EllipticFScalar(math.Atan(1/eps), 1-m1) /
		(float64(order) * core.EllipticKScalar(m1))
	sv := jacobiScalar(core.JacobiSN, v0, 1-m)
	cv := jacobiScalar(core.JacobiCN, v0, 1-m)
	dv := jacobiScalar(core.JacobiDN, v0, 1-m)

	poles := make([]complex128, 0, order)
	for _, a := range amplitudes {
		s, c, d := a[0], a[1], a[2]
		p := -complex(c*d*sv*cv, s*dv) / (1 - complex((d*sv)*(d*sv), 0))
		if math.Abs(imag(p)) < 1e-10 {
			poles = append(poles, complex(real(p), 0))
			continue
		}
		poles = append(poles, p, cmplx.Conj(p))
	}
	gain := 1.0
	if order%2 == 0 {
		gain = 1 / math.Sqrt(1+epsSq)
	}
	return prototype{poles: poles, zeros: zeroes,
		zerosAtInfinity: order - len(zeroes), gain: gain}
}

// ellipdeg solves the degree equation n·K(m)/K'(m) = K(m1)/K'(m1)
// for m through the nome q = exp(−π·K'/K), whose theta product is
// accurate to double precision within the first eight powers.
func ellipdeg(n int, m1 float64) float64 {
	k1 := core.EllipticKScalar(m1)
	k1p := core.EllipticKScalar(1 - m1)
	q := math.Pow(math.Exp(-math.Pi*k1p/k1), 1.0/float64(n))
	num, den := 1.0, 1.0
	for k := 1; k <= 7; k++ {
		num += math.Pow(q, float64(k*(k+1)))
	}
	for k := 1; k <= 8; k++ {
		den += 2 * math.Pow(q, float64(k*k))
	}
	return 16 * q * math.Pow(num/den, 4)
}

// jacobiScalar reads one Jacobi function at one point through the
// array implementation, which inverts the amplitude by bracketed
// Newton against Carlson's incomplete integral.
func jacobiScalar(f func(u *core.Array, m float64) (*core.Array, error), u, m float64) float64 {
	arr, err := core.FromFloats([]float64{u}, 1)
	if err != nil {
		return math.NaN()
	}
	out, err := f(arr, m)
	if err != nil {
		return math.NaN()
	}
	return out.FloatAt(0)
}

// mapEdge transforms one analog root of the unit-edge prototype into
// the prewarped target band. Band roots come back as the pair of a
// quadratic, the pairing surviving because the map sends conjugate
// pairs to conjugate pairs.
func mapEdge(s complex128, sh shape, w1, w2 float64) []complex128 {
	switch sh {
	case lowPass:
		return []complex128{s * complex(w1, 0)}
	case highPass:
		return []complex128{complex(w1, 0) / s}
	case bandPass:
		// Scale to the half bandwidth, then split about the centre:
		// the pair solves s² − BW·root·s + w0² = 0.
		half := s * complex((w2-w1)/2, 0)
		disc := cmplx.Sqrt(half*half - complex(w1*w2, 0))
		return []complex128{half + disc, half - disc}
	default: // bandStop: invert to the half-bandwidth high-pass, then
		// split about the centre the same way.
		half := complex((w2-w1)/2, 0) / s
		disc := cmplx.Sqrt(half*half - complex(w1*w2, 0))
		return []complex128{half + disc, half - disc}
	}
}

// shape picks the band the design passes.
type shape int

const (
	lowPass shape = iota
	highPass
	bandPass
	bandStop
)

// design runs the shared road from prototype to coefficients: shape
// transformation of every root, bilinear mapping, assembly into real
// u = z⁻¹ polynomials, and the gain taken from the prototype itself
// at its DC, which every shape reaches through the mapping (the
// low-pass at DC, the high-pass at Nyquist, the band pair at the
// band centre and DC respectively).
func design(sh shape, proto prototype, w1, w2 float64) (b, a []float64, err error) {
	const name = "filter design"
	// Denominator roots: every pole, shape-transformed and mapped.
	var poles []complex128
	for _, p := range proto.poles {
		for _, s := range mapEdge(p, sh, w1, w2) {
			if real(s) > 1e-7*(1+cmplx.Abs(s)) {
				return nil, nil, base.Errf("%s: a pole escaped the left half-plane", name)
			}
			poles = append(poles, bilinear(s))
		}
	}
	// Numerator roots: every finite zero's image, then the zeroes at
	// infinity: (1+u) factors for the low-pass, whose infinity maps
	// to u = −1; (1−u) pairs for the band-pass, whose infinity maps
	// to s = 0, u = 1; and one ±j·w0 conjugate pair per zero for the
	// band-stop. The infinity factors are digital already; only the
	// finite zeroes pass through the bilinear map.
	var zeros []complex128
	for _, z := range proto.zeros {
		zeros = append(zeros, mapEdge(z, sh, w1, w2)...)
	}
	zeros = bilinearAll(zeros)
	zeros = append(zeros, infinityFactors(sh, proto.zerosAtInfinity, math.Sqrt(w1*w2))...)
	b, err = assembleRoots(zeros)
	if err != nil {
		return nil, nil, err
	}
	a, err = assembleRoots(poles)
	if err != nil {
		return nil, nil, err
	}
	// Gain: the prototype's gain field is the response the design
	// promises at its reference point (the passband peak, one or
	// 1/sqrt(1+eps²) by order parity), so the numerator scales until
	// the digital response at the mapped reference equals it.
	var uRef complex128
	switch sh {
	case lowPass, bandStop:
		uRef = 1
	case highPass:
		uRef = -1
	default: // bandPass: the band centre, the geometric mean edge; the
		// conjugate side keeps the polynomial evaluation real.
		uRef = cmplx.Conj(bilinear(complex(0, math.Sqrt(w1*w2))))
	}
	hd := polyEvalC(b, uRef) / polyEvalC(a, uRef)
	if hd == 0 {
		return nil, nil, base.Errf("%s: the reference point carries no gain", name)
	}
	// The magnitude is what the gain field promises; the phase at the
	// reference follows from the roots and is no business of the
	// scaling.
	scale := proto.gain / cmplx.Abs(hd)
	for i := range b {
		b[i] *= scale
	}
	return b, a, nil
}

// infinityFactors names the numerator roots the prototype's zeroes at
// infinity turn into after the shape transformation: the low-pass
// zeroes at s = ∞ land at u = −1; the high-pass zeroes at s = 0 land
// at u = +1; the band-pass substitution squares its frequency, so
// every infinity zero becomes a double zero at s = 0, two (1−u)
// factors; and the band-stop turns every infinity zero into the
// conjugate pair ±j·w0, the roots of s² + w0² = 0.
func infinityFactors(sh shape, atInfinity int, w0 float64) []complex128 {
	switch sh {
	case lowPass:
		roots := make([]complex128, 0, atInfinity)
		for range atInfinity {
			roots = append(roots, -1)
		}
		return roots
	case bandPass:
		// The substitution's s = (1−u)/(1+u) leaves the numerator as
		// (1−u²)^N: half the roots at u = 1, half at u = −1.
		roots := make([]complex128, 0, 2*atInfinity)
		for range atInfinity {
			roots = append(roots, 1, -1)
		}
		return roots
	case bandStop:
		roots := make([]complex128, 0, 2*atInfinity)
		for range atInfinity {
			d := bilinear(complex(0, w0))
			roots = append(roots, d, cmplx.Conj(d))
		}
		return roots
	default: // highPass
		roots := make([]complex128, 0, atInfinity)
		for range atInfinity {
			roots = append(roots, 1)
		}
		return roots
	}
}

// assembleRoots factors digital roots into a real polynomial in u =
// z⁻¹: conjugate pairs become the real quadratic
// (1 − z·u)(1 − z̄·u) = 1 − 2Re(z)·u + |z|²·u², real roots the linear
// factor (1 − z·u). The pairing matches each root against the
// remaining roots' conjugates, so it does not depend on the order
// the roots arrived in.
func assembleRoots(roots []complex128) ([]float64, error) {
	const name = "filter design"
	poly := []float64{1}
	used := make([]bool, len(roots))
	for i, r := range roots {
		if used[i] {
			continue
		}
		if math.Abs(imag(r)) < 1e-9 {
			used[i] = true
			poly = mulPolyReal(poly, []float64{1, -real(r)})
			continue
		}
		// The nearest conjugate partner among the unused roots.
		partner := -1
		best := math.Inf(1)
		for j := i + 1; j < len(roots); j++ {
			if used[j] {
				continue
			}
			if d := cmplx.Abs(roots[j] - cmplx.Conj(r)); d < best {
				best, partner = d, j
			}
		}
		if partner < 0 || best > 1e-6*cmplx.Abs(r) {
			return nil, base.Errf("%s: the roots lost their conjugate symmetry", name)
		}
		used[partner] = true
		poly = mulPolyReal(poly, []float64{1, -2 * real(r), real(r * cmplx.Conj(r))})
	}
	return poly, nil
}

// bilinearAll maps a root list through the bilinear transform.
func bilinearAll(roots []complex128) []complex128 {
	out := make([]complex128, len(roots))
	for i, s := range roots {
		out[i] = bilinear(s)
	}
	return out
}

// bilinear maps an analog root to its digital image, the T = 2
// sampling the prewarp assumes.
func bilinear(s complex128) complex128 {
	return (1 + s) / (1 - s)
}

// polyEvalC evaluates a u = z⁻¹ polynomial at one complex point.
func polyEvalC(poly []float64, u complex128) complex128 {
	total := complex(0, 0)
	for _, p := range slices.Backward(poly) {
		total = total*u + complex(p, 0)
	}
	return total
}

// The public designs. Each validates its arguments, prewarps the
// edges, and hands the shared road its prototype.

// designArgs bundles the validated prewarped edges for one call.
func designArgs(name string, order int, fs, edge1, edge2 float64, sh shape) (w1, w2 float64, err error) {
	if order < 1 {
		return 0, 0, base.Errf("%s: the order must be at least 1, got %d", name, order)
	}
	if !(fs > 0) || math.IsInf(fs, 0) {
		return 0, 0, base.Errf("%s: fs must be positive and finite, got %g", name, fs)
	}
	if !(edge1 > 0) || edge1 >= fs/2 {
		return 0, 0, base.Errf("%s: the edge must lie in (0, fs/2), got %g for fs %g", name, edge1, fs)
	}
	w1 = math.Tan(math.Pi * edge1 / fs)
	if sh == bandPass || sh == bandStop {
		if !(edge2 > edge1) || edge2 >= fs/2 {
			return 0, 0, base.Errf("%s: the band must span (edge1, edge2) inside (0, fs/2), got %g, %g for fs %g",
				name, edge1, edge2, fs)
		}
		w2 = math.Tan(math.Pi * edge2 / fs)
	}
	return w1, w2, nil
}

// ChebyshevLowPass designs an order-N type I Chebyshev low-pass at fs
// hertz with its ripple in decibels: the passband oscillates between
// 0 and -rippleDB, the edge is the last touch of -rippleDB, and the
// stopband rolls off as fast as that budget allows.
func ChebyshevLowPass(order int, fs, cutoff, rippleDB float64) (b, a []float64, err error) {
	const name = "ChebyshevLowPass"
	if rippleDB <= 0 {
		return nil, nil, base.Errf("%s: the ripple must be positive decibels, got %g", name, rippleDB)
	}
	w, _, err := designArgs(name, order, fs, cutoff, 0, lowPass)
	if err != nil {
		return nil, nil, err
	}
	return design(lowPass, chebyshev1(order, rippleDB), w, 0)
}

// ChebyshevHighPass is the type I mirror: the same equiripple
// passband above the edge, rolling off below it.
func ChebyshevHighPass(order int, fs, cutoff, rippleDB float64) (b, a []float64, err error) {
	const name = "ChebyshevHighPass"
	if rippleDB <= 0 {
		return nil, nil, base.Errf("%s: the ripple must be positive decibels, got %g", name, rippleDB)
	}
	w, _, err := designArgs(name, order, fs, cutoff, 0, highPass)
	if err != nil {
		return nil, nil, err
	}
	return design(highPass, chebyshev1(order, rippleDB), w, 0)
}

// InverseChebyshevLowPass designs the type II low-pass: a flat
// passband through the edge, with the stopband bottoming out at
// -stopbandDB and equiripple beyond it.
func InverseChebyshevLowPass(order int, fs, cutoff, stopbandDB float64) (b, a []float64, err error) {
	const name = "InverseChebyshevLowPass"
	if stopbandDB <= 0 {
		return nil, nil, base.Errf("%s: the stopband attenuation must be positive decibels, got %g", name, stopbandDB)
	}
	w, _, err := designArgs(name, order, fs, cutoff, 0, lowPass)
	if err != nil {
		return nil, nil, err
	}
	return design(lowPass, chebyshev2(order, stopbandDB), w, 0)
}

// InverseChebyshevHighPass is the type II mirror above the edge.
func InverseChebyshevHighPass(order int, fs, cutoff, stopbandDB float64) (b, a []float64, err error) {
	const name = "InverseChebyshevHighPass"
	if stopbandDB <= 0 {
		return nil, nil, base.Errf("%s: the stopband attenuation must be positive decibels, got %g", name, stopbandDB)
	}
	w, _, err := designArgs(name, order, fs, cutoff, 0, highPass)
	if err != nil {
		return nil, nil, err
	}
	return design(highPass, chebyshev2(order, stopbandDB), w, 0)
}

// CauerLowPass designs the elliptic low-pass: equiripple in the
// passband within rippleDB and equiripple stopband not above
// -stopbandDB, with the narrowest transition of any design at the
// order. The zeroes sit in the stopband, finite and on the unit
// circle after mapping.
func CauerLowPass(order int, fs, cutoff, rippleDB, stopbandDB float64) (b, a []float64, err error) {
	const name = "CauerLowPass"
	if rippleDB <= 0 || stopbandDB <= rippleDB {
		return nil, nil, base.Errf("%s: the ripple must be positive and the attenuation larger, got %g and %g",
			name, rippleDB, stopbandDB)
	}
	w, _, err := designArgs(name, order, fs, cutoff, 0, lowPass)
	if err != nil {
		return nil, nil, err
	}
	return design(lowPass, cauer(order, rippleDB, stopbandDB), w, 0)
}

// CauerHighPass is the elliptic mirror above the edge.
func CauerHighPass(order int, fs, cutoff, rippleDB, stopbandDB float64) (b, a []float64, err error) {
	const name = "CauerHighPass"
	if rippleDB <= 0 || stopbandDB <= rippleDB {
		return nil, nil, base.Errf("%s: the ripple must be positive and the attenuation larger, got %g and %g",
			name, rippleDB, stopbandDB)
	}
	w, _, err := designArgs(name, order, fs, cutoff, 0, highPass)
	if err != nil {
		return nil, nil, err
	}
	return design(highPass, cauer(order, rippleDB, stopbandDB), w, 0)
}

// ChebyshevBandPass designs the type I band-pass spanning edge1 to
// edge2: the prototype's order doubles through the band move.
func ChebyshevBandPass(order int, fs, edge1, edge2, rippleDB float64) (b, a []float64, err error) {
	const name = "ChebyshevBandPass"
	if rippleDB <= 0 {
		return nil, nil, base.Errf("%s: the ripple must be positive decibels, got %g", name, rippleDB)
	}
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandPass)
	if err != nil {
		return nil, nil, err
	}
	return design(bandPass, chebyshev1(order, rippleDB), w1, w2)
}

// ChebyshevBandStop designs the type I band-stop.
func ChebyshevBandStop(order int, fs, edge1, edge2, rippleDB float64) (b, a []float64, err error) {
	const name = "ChebyshevBandStop"
	if rippleDB <= 0 {
		return nil, nil, base.Errf("%s: the ripple must be positive decibels, got %g", name, rippleDB)
	}
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandStop)
	if err != nil {
		return nil, nil, err
	}
	return design(bandStop, chebyshev1(order, rippleDB), w1, w2)
}

// InverseChebyshevBandPass designs the type II band-pass.
func InverseChebyshevBandPass(order int, fs, edge1, edge2, stopbandDB float64) (b, a []float64, err error) {
	const name = "InverseChebyshevBandPass"
	if stopbandDB <= 0 {
		return nil, nil, base.Errf("%s: the stopband attenuation must be positive decibels, got %g", name, stopbandDB)
	}
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandPass)
	if err != nil {
		return nil, nil, err
	}
	return design(bandPass, chebyshev2(order, stopbandDB), w1, w2)
}

// InverseChebyshevBandStop designs the type II band-stop.
func InverseChebyshevBandStop(order int, fs, edge1, edge2, stopbandDB float64) (b, a []float64, err error) {
	const name = "InverseChebyshevBandStop"
	if stopbandDB <= 0 {
		return nil, nil, base.Errf("%s: the stopband attenuation must be positive decibels, got %g", name, stopbandDB)
	}
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandStop)
	if err != nil {
		return nil, nil, err
	}
	return design(bandStop, chebyshev2(order, stopbandDB), w1, w2)
}

// CauerBandPass designs the elliptic band-pass.
func CauerBandPass(order int, fs, edge1, edge2, rippleDB, stopbandDB float64) (b, a []float64, err error) {
	const name = "CauerBandPass"
	if rippleDB <= 0 || stopbandDB <= rippleDB {
		return nil, nil, base.Errf("%s: the ripple must be positive and the attenuation larger, got %g and %g",
			name, rippleDB, stopbandDB)
	}
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandPass)
	if err != nil {
		return nil, nil, err
	}
	return design(bandPass, cauer(order, rippleDB, stopbandDB), w1, w2)
}

// CauerBandStop designs the elliptic band-stop.
func CauerBandStop(order int, fs, edge1, edge2, rippleDB, stopbandDB float64) (b, a []float64, err error) {
	const name = "CauerBandStop"
	if rippleDB <= 0 || stopbandDB <= rippleDB {
		return nil, nil, base.Errf("%s: the ripple must be positive and the attenuation larger, got %g and %g",
			name, rippleDB, stopbandDB)
	}
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandStop)
	if err != nil {
		return nil, nil, err
	}
	return design(bandStop, cauer(order, rippleDB, stopbandDB), w1, w2)
}

// ButterworthBandPass designs the maximally flat band-pass.
func ButterworthBandPass(order int, fs, edge1, edge2 float64) (b, a []float64, err error) {
	const name = "ButterworthBandPass"
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandPass)
	if err != nil {
		return nil, nil, err
	}
	return design(bandPass, butterworthPrototype(order), w1, w2)
}

// ButterworthBandStop designs the maximally flat band-stop.
func ButterworthBandStop(order int, fs, edge1, edge2 float64) (b, a []float64, err error) {
	const name = "ButterworthBandStop"
	w1, w2, err := designArgs(name, order, fs, edge1, edge2, bandStop)
	if err != nil {
		return nil, nil, err
	}
	return design(bandStop, butterworthPrototype(order), w1, w2)
}

// butterworthPrototype rebuilds the maximally flat poles in the
// prototype shape, so the band shapes share the same road; the
// existing ButterworthLowPass and ButterworthHighPass keep their own
// pinned implementations untouched.
func butterworthPrototype(order int) prototype {
	poles := make([]complex128, 0, order)
	for k := range order {
		theta := math.Pi * float64(2*k+1) / float64(2*order)
		// One Sincos serves the pole's both factors, the same pair the
		// separate calls produced.
		sinT, cosT := math.Sincos(theta)
		if math.Abs(cosT) < 1e-15 {
			poles = append(poles, complex(-1, 0))
			continue
		}
		if cosT < 0 {
			continue // the mirror angle's conjugate, already stored
		}
		p := complex(-sinT, cosT)
		poles = append(poles, p, cmplx.Conj(p))
	}
	return prototype{poles: poles, zerosAtInfinity: order, gain: 1}
}