docs/SCIENTIFIC_VALIDATION.md

# Sofia Engine Scientific Validation

All algorithms in Sofia Engine are backed by deterministic mathematical verification, golden test vectors, and physical conservation laws.

---

## 1. Digital Signal Processing Correctness

### Parseval Energy Conservation
For discrete signals, Parseval's theorem dictates that total energy in the time domain must equal total energy in the frequency domain:
$$\sum_{n=0}^{N-1} |x[n]|^2 = \frac{1}{N} \sum_{k=0}^{N-1} |X[k]|^2$$

When applying window functions $w[n]$, energy is attenuated by the noise power bandwidth gain:
$$S_2 = \sum_{n=0}^{N-1} w[n]^2$$

Sofia's `welch_psd` implementation normalizes power spectral density by $S_2$ and frequency resolution $\Delta f = f_s / N$. Energy conservation across Hann, Hamming, and Blackman windows is continuously verified in `tests/unit/test_dsp_golden.py`:
$$\left| \frac{\int \text{PSD}(f)\,df}{\text{Var}(x)} - 1.0 \right| < 0.05$$

### Exact Amplitude Recovery
For unwindowed integer-bin tones ($f_0 = k \cdot f_s / N$), the one-sided FFT magnitude recovers the exact continuous amplitude $A$:
$$\hat{A} = \frac{2}{N} |X[k]|$$
Sofia verifies peak tone amplitude recovery to machine precision ($< 10^{-14}$ relative error).

### 3-Phase Symmetrical Components (Fortescue Transformation)
Unbalanced 3-phase voltages $V_a, V_b, V_c$ are decomposed using the complex operator $a = e^{j 120^\circ} = -\frac{1}{2} + j \frac{\sqrt{3}}{2}$:
$$\begin{bmatrix} V_0 \\ V_1 \\ V_2 \end{bmatrix} = \frac{1}{3} \begin{bmatrix} 1 & 1 & 1 \\ 1 & a & a^2 \\ 1 & a^2 & a \end{bmatrix} \begin{bmatrix} V_a \\ V_b \\ V_c \end{bmatrix}$$
$$\text{VUF} = \frac{|V_2|}{|V_1|} \times 100\%$$
Golden vectors generated in `tests/golden/dsp_golden.json` assert that positive ($V_1$), negative ($V_2$), and zero ($V_0$) sequence components match theoretical values within $10^{-5}$ tolerance across Python, TypeScript, and C99 runtimes.

---

## 2. In-Situ Neural Training & Gradient Verification

Sofia's virtual assembly neural network (`AssemblyNeuralNetwork`) implements 2-layer analytical backpropagation directly in virtual bytecode:
$$\frac{\partial L}{\partial W_2} = \frac{\partial L}{\partial \hat{y}} \cdot h^T, \quad \frac{\partial L}{\partial B_2} = \frac{\partial L}{\partial \hat{y}}$$
$$\frac{\partial L}{\partial h} = W_2^T \cdot \frac{\partial L}{\partial \hat{y}}, \quad \frac{\partial L}{\partial z_1} = \frac{\partial L}{\partial h} \odot \mathbb{I}(z_1 > 0)$$
$$\frac{\partial L}{\partial W_1} = \frac{\partial L}{\partial z_1} \cdot x^T, \quad \frac{\partial L}{\partial B_1} = \frac{\partial L}{\partial z_1}$$

Analytical gradients computed in virtual registers are validated against central finite differences:
$$\frac{\partial L}{\partial \theta_i} \approx \frac{L(\theta_i + \epsilon) - L(\theta_i - \epsilon)}{2\epsilon}, \quad \epsilon = 10^{-5}$$
The relative error $\frac{\|\nabla_{\text{analytical}} - \nabla_{\text{numerical}}\|}{\|\nabla_{\text{analytical}}\| + \|\nabla_{\text{numerical}}\|}$ is proven to be $< 10^{-5}$ in `tests/unit/test_neural_gradients.py`.

---

## 3. Microcontroller Fixed-Point Conformance

The C99 embedded runtime (`embedded/src/sofia_features.c`) implements Q16.16 fixed-point arithmetic:
- Fixed-point resolution: $1/65536 \approx 1.526 \times 10^{-5}$
- Dynamic range: $[-32768.0, +32767.99998]$
- Zero heap allocation: no calls to `malloc`, `calloc`, or `free` post-initialization.
- Compile-time static ceilings: `SOFIA_MAX_FFT_LEN = 1024`, `SOFIA_N_STAT_FEATURES = 14`.