galileo/docs/fixed_point_plan.md

Fixed-point plan

The fixed framework represents signed two's-complement integers with declared total/fractional widths. Every quantizer selects saturation or wrap and nearest, truncate, or convergent ties-to-even rounding. Quantizers count overflow and accumulate RMS/peak quantization error.

Proposed starting points (not final widths):

Stage	Width	Fraction	Policy
input sample	8	7	saturate
sine/cosine	16	15	saturate
mixer output	18	15	saturate
FFT input	18	15	saturate
FFT twiddle	16	15	convergent
FFT stage	20	15	configured scaling
correlation product	36	30	full precision then requantize
IFFT output	28	15	saturate
coherent accumulator	40	15	saturate
noncoherent accumulator	unsigned 56	20	saturate
carrier phase	unsigned 32	0	natural wrap
code phase	unsigned 48	32	natural wrap
loop state	32	20	saturate
FCW	signed 32	0	wrap in phase accumulator
discriminator	24	18	saturate

FixedNco and FixedCorrelator are integer bit-true models. Fixed PCPS models declared quantization at input, normalized FFT output, pointwise product, IFFT output/power, and accumulation. Exact butterfly-level identity depends on the chosen streaming FFT IP scaling schedule and is explicitly unresolved until an RTL FFT architecture is selected.

FixedRadix2Fft supplies a fully stage-quantized power-of-two oracle with quantized twiddles, convergent butterfly rounding, saturation counters, and one bit of scaling per stage. It is used for standalone RTL FFT vectors. The runtime PCPS boundary model remains able to use arbitrary transform lengths; matching a vendor FFT at those lengths requires configuring that core's exact schedule.

The sweep utility varies input/FFT widths and reports mean absolute/relative, RMS, peak error, acquisition decision, Doppler bin, code phase, and overflows. Tracking qualification additionally compares convergence, steady-state jitter, and loss-of-lock decisions; these metrics must become release gates once loop state formats are frozen.