DP44/docs/ai/DataPRO/ExocortexDSP.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/ExocortexDSP/Polynomial.cs DataPRO/ExocortexDSP/FourierDirection.cs DataPRO/ExocortexDSP/AssemblyInfo.cs DataPRO/ExocortexDSP/ComplexMath.cs DataPRO/ExocortexDSP/PassFilter.cs DataPRO/ExocortexDSP/ComplexStats.cs DataPRO/ExocortexDSP/Complex.cs	2026-04-17T15:48:44.861058+00:00	zai-org/GLM-5-FP8	1	df53e9f2f708d29c

Documentation: Exocortex.DSP Namespace

1. Purpose

The Exocortex.DSP namespace provides a library for Digital Signal Processing (DSP) utilities within the DataPRO system. It offers core data structures for representing double-precision and single-precision complex numbers, mathematical operations for complex arithmetic (roots, powers), statistical analysis tools for complex datasets, and frequency-domain filtering capabilities (Butterworth, Chebyshev, Bessel). It serves as the mathematical backbone for signal manipulation tasks, enabling transformations between time and frequency domains.

2. Public Interface

Structs

Complex A double-precision complex number representation.

• public double Re: The real component.
• public double Im: The imaginary component.
• public Complex(double real, double imaginary): Constructor.
• static public Complex FromRealImaginary(double real, double imaginary): Factory method.
• static public Complex FromModulusArgument(double modulus, double argument): Factory method creating a complex number from polar coordinates.
• public double GetModulus(): Returns the magnitude \sqrt{Re^2 + Im^2}.
• public double GetModulusSquared(): Returns Re^2 + Im^2.
• public double GetArgument(): Returns the angle in radians.
• public Complex GetConjugate(): Returns the complex conjugate.
• public void Normalize(): Scales the number to a magnitude of 1.
• static public bool IsEqual(Complex a, Complex b, double tolerance): Compares two numbers within a tolerance.
• static public Complex Zero: Represents (0, 0).
• static public Complex I: Represents (0, 1).
• Operators: +, -, *, / (supporting Complex and double operands), ==, !=.

Classes

ComplexMath Static utility class for complex number mathematics.

• static public void Swap(ref Complex a, ref Complex b): Swaps two complex numbers.
• static public void Swap(ref ComplexF a, ref ComplexF b): Swaps two single-precision complex numbers.
• static public Complex Sqrt(Complex c): Calculates the square root.
• static public ComplexF Sqrt(ComplexF c): Calculates the square root (single-precision).
• static public Complex Pow(Complex c, double exponent): Raises a complex number to a power.
• static public ComplexF Pow(ComplexF c, double exponent): Raises a complex number to a power (single-precision).

ComplexStats Static utility class for statistical operations on arrays of complex numbers.

• static public Complex Sum(Complex[] data): Calculates the sum.
• static public Complex SumOfSquares(Complex[] data): Calculates the sum of squares.
• static public Complex Mean(Complex[] data): Calculates the mean.
• static public Complex Variance(Complex[] data): Calculates the variance.
• static public Complex StdDev(Complex[] data): Calculates the standard deviation.
• static public double RMSError(Complex[] alpha, Complex[] beta): Calculates the Root Mean Squared Error between two datasets.
• Note: Overloads for ComplexF[] exist for all the above methods.

PassFilter Static class for applying frequency-domain filters.

• static public double[] HighPass(double[] values, double sampleRate, double centerFrequency, PassFilterType type, uint order): Applies a high-pass filter.
• static public double[] LowPass(double[] values, double sampleRate, double centerFrequency, PassFilterType type, uint order): Applies a low-pass filter.

Polynomial (Abstract) Base class for polynomial representations.

• public Polynomial(params double[] coefficients): Constructor.
• public abstract double Evaluate(double value): Evaluates the polynomial at a specific value.
• public double GetCoefficient(int index): Retrieves a coefficient by index.

SimplePolynomial A concrete implementation of Polynomial.

• public SimplePolynomial(params double[] coefficients): Constructor.
• public override double Evaluate(double value): Evaluates the polynomial using a loop (calculates c_0 + c_1x + c_2x^2 + \dots).

Enums

FourierDirection Specifies the direction of a Fourier Transform.

• Forward = 1: Time to frequency domain.
• Backward = -1: Frequency to time domain.

PassFilterType Specifies the type of filter algorithm.

• Bessel, Butterworth, Chebyshev, CriticalDamping.

3. Invariants

• Coefficient Storage: In Polynomial, coefficients are stored in ascending order of power (index 0 is the constant term c_0). This is confirmed by SimplePolynomial.Evaluate where coefficients[0] is the starting value and subsequent coefficients are multiplied by increasing powers of value.
• Immutability of Inputs: PassFilter methods (HighPass, LowPass) do not modify the input values array; they clone the internal complex representation before processing.
• FFT Scaling: PassFilter methods scale the result of the inverse FFT by dividing by the signal length N. This is required to normalize the output of Fourier.FFT with FourierDirection.Backward.
• Index Bounds: Polynomial.GetCoefficient returns double.NaN if the index is out of bounds or if the coefficient array is null, rather than throwing an exception.
• Comparison Logic: Complex.CompareTo compares instances based on their Modulus (magnitude), not their real or imaginary components individually.

4. Dependencies

Internal Dependencies (within this namespace):

• PassFilter depends on Complex, FourierDirection, Polynomial, and SimplePolynomial.
• ComplexStats depends on Complex, ComplexF, and ComplexMath.
• ComplexMath depends on Complex and ComplexF.

External Dependencies:

• System: Basic types (Math, Double, Array, etc.).
• System.Linq: Used heavily in PassFilter for projection (.Select) and in ComplexStats.
• System.Threading.Tasks: Used in PassFilter for parallel processing of frequency bins (Parallel.For).
• System.Runtime.InteropServices: Used in Complex for StructLayout(LayoutKind.Sequential).

Missing/Inferred Dependencies:

• ComplexF: Referenced in ComplexMath and ComplexStats but the definition is not present in the provided source files.
• Fourier: The static class Fourier is invoked in PassFilter (e.g., Fourier.FFT(signal, N, FourierDirection.Forward)), but the definition is not present in the provided source files.

5. Gotchas

• Missing Implementation (Complex.Parse): The Complex.Parse(string s) method exists in the signature but throws a NotImplementedException if called.
• Mutation in Math Methods: The static methods ComplexMath.Sqrt(Complex c) and ComplexMath.Pow(Complex c, double exponent) mutate the passed-in struct c (modifying c.Re and c.Im) and return it. This is unusual for static math utilities which typically return a new instance.
• Precision Loss in Operator: The subtraction operator public static Complex operator -(double f, Complex a) casts the result components to float before assigning them back to the Complex (double) struct:

  a.Re = (float)(f - a.Re); // Precision loss here
  a.Im = (float)(0 - a.Im); // Precision loss here
  

  This appears to be a bug or legacy artifact, as it reduces precision for double-precision math.
• Hardcoded Filter Parameters: The public API for PassFilter does not expose ripple or DC gain parameters. RunFilter hardcodes DCGain = 1D for Butterworth/Chebyshev and ripple = 0.005 for Chebyshev.
• Limited Polynomial Support: PassFilter.ChebyshevPolynomial and PassFilter.BesselDenominatorPolynomial throw NotImplementedException for orders greater than 8 (Chebyshev) or outside the range 2-8 (Bessel).
• DC Offset Removal: PassFilter.ChebyshevFilter explicitly sets signal[0] = 0 (removing DC offset) inside the FFT domain. The Bessel and Butterworth implementations do not do this; they preserve the DC component (unless the gain function naturally attenuates it).