# Spectral engine validation

Validation date: 2026-09-27

## Outcome

The prototype preserves three truth layers: physical spectral state, standard-observer response, and display output. It now also renders a sphere, block, table, and moving shadows from an explicit direct-light model. The numerical matrix engine still reconstructs every benchmark at floating-point precision, while the light module passes wavelength, observer, energy, colour, interference, and scene-behavior tests.

## Reference data

- Dataset: CIE 1931 colour-matching functions, 2 degree observer
- Source: `https://cie.co.at/datatable/cie-1931-colour-matching-functions-2-degree-observer`
- File: `CIE_xyz_1931_2deg.csv`
- Sampling: 360–830 nm inclusive, 1 nm increments, 471 rows
- Verified MD5: `17cca777db64b17170f06f67ce9d3ab7`
- Photopic y-bar maximum in the supplied table: 555 nm

The standalone app embeds this table. The CSV remains in the source package so the embedded payload can be rebuilt and audited.

## Models implemented

### Vacuum wavelength and frequency

The conversion uses the defined speed of light:

\[
f = \frac{c}{\lambda}, \qquad c = 299\,792\,458\;\text{m/s}.
\]

### Spectral power to standard-observer response

For sampled spectral power distribution \(S(\lambda)\):

\[
(X,Y,Z) = \int S(\lambda)\,[\bar{x}(\lambda),\bar{y}(\lambda),\bar{z}(\lambda)]\,d\lambda.
\]

The engine can preserve absolute linear XYZ or normalize to \(Y=1\) for display preview. Values outside the CIE table have zero standard-observer response but remain present in the physical spectrum.

### Interference

For coherent equal-frequency fields, complex amplitudes add before intensity is calculated:

\[
I = \left|\sum_k A_k e^{i\phi_k}\right|^2.
\]

For mutually incoherent components, intensities add:

\[
I = \sum_k A_k^2.
\]

Two unit-amplitude, equal-phase waves therefore produce relative intensity 4; a phase separation of pi produces numerical zero; the incoherent sum is 2.

The interactive optics renderer combines only sources with **exactly equal wavelength** coherently. Different frequencies have no retained cross term after its detector-time average. Its scene uses a point-source irradiance proportional to \(P/(4\pi r^2)\), a cosine incidence term, Lambertian diffuse surface response, and an occlusion ray for hard shadows. Reflected light is integrated through CIE colour matching and mapped to sRGB. Reflectance spectra are illustrative smooth curves constrained to the interval \([0,1]\), and the environment adds a fixed low level of neutral light.

At 555 nm, light oscillates at approximately \(5.40\times10^{14}\) Hz. A 35 ms window spans approximately \(1.89\times10^{13}\) cycles. The simulation integrates that optical carrier analytically; it changes lamp and camera positions at interactive frame rates.

## Automated verification

Command:

```bash
python -m unittest discover -s tests -v
```

Result: **23/23 tests passed**.

| Check | Result |
|---|---:|
| Official CIE file identity | Exact MD5 match |
| CIE grid | 471 ordered 1 nm samples |
| Wavelength/frequency round trip | Within floating-point precision |
| y-bar peak | 555 nm |
| Observer response outside table | Zero |
| Linear unnormalized XYZ addition | Passed |
| sRGB finite and bounded | Passed |
| Visible + hidden fractions | Sum to 1 |
| Constructive/destructive interference | 4 / approximately 0 |
| Matrix rotor full reconstruction | Below `2e-14` relative error on all benchmarks |
| Standalone app has no external code/style dependency | Passed |
| Embedded CIE data equals source CSV | Exact array match |
| HTML IDs and JavaScript references | Unique and complete |
| JavaScript syntax | Passed `node --check` |
| Object intersections and ray ordering | Passed in `node tools/check_optics.cjs` |
| Shadow blocker geometry | Passed |
| Same-wavelength cancellation and different-wavelength independence | Passed |
| Spectral reflectance contrast between sphere and block | Passed |
| Doubled source power changes brightness | Passed |
| UV source has no CIE visible contribution | Passed |
| Stationary source produces a stable time-averaged image | Passed |
| Moving source changes rendered image | Passed |
| Same-wavelength phase cancellation changes rendered image | Passed |

The reproducible demonstration in `run_spectral_demo.py` creates a 250–2500 nm spectrum containing UV, visible, and IR power. Its current fixture contains 39.9833% power inside the CIE table band and 60.0167% outside it. The visible projection is normalized XYZ `[1.05608, 1.00000, 0.85441]` and display-mapped sRGB `[1.00000, 0.80277, 0.74808]`.

## Exact, standardized, and illustrative parts

| Status | Component |
|---|---|
| Exact definition | Speed of light used in wavelength/frequency conversion |
| Exact file identity | Bundled CIE table bytes match the published checksum |
| Standardized model | CIE 1931 2° colour matching and sRGB transfer curve |
| Numerically exact within floating point | Full Fourier-rotor matrix reconstruction |
| Physically correct simplified model | Coherent phasor addition for equal-frequency scalar waves |
| Physically grounded approximation | Spectral direct-light ray tracing with opaque hard shadows and diffuse reflectance |
| Illustrative | Helical 3D strand geometry, matrix surface styling, material reflectance curves, time scaling, and hidden-wave false colour |
| Approximate diagnostic | Adjustable observer temporal window |
| Not implemented yet | Vector Maxwell solver, polarization, measured media/dispersion, diffraction, multiple light bounces, absolute radiometric calibration, eye adaptation, rod/cone physiology, and colour appearance models |

## Interpretation

The computer can retain and evolve more spectral information than the eye or a monitor can present. It cannot make UV or infrared literally visible one-to-one. This implementation preserves those waves as physical data, shows a calibrated human-observer projection, and provides a separately labeled false-colour diagnostic for hidden bands. The new scene demonstrates image formation through geometric optics and spectral reflection, while the surrounding rotor geometry remains a model for inspection rather than an electromagnetic field solution.