starkernel: item 4.3.3a -- Q48.16 trigonometry (Q.SIN/Q.COS)

Adds q48_reduce_angle() (range-reduce a signed Q48.16 angle into
[-PI_Q48, PI_Q48] via one integer division plus a bounded fix-up loop) and
q48_sin_approx/q48_cos_approx (Taylor series, terms n=3,5,7,9,11 for sin
and n=2,4,6,8,10 for cos, early exit below 10). Q.SIN/Q.COS registered as
FORTH words in q48_words.c, same pattern as Q.LOG/Q.EXP/Q.SQRT.

Found mid-implementation: this codebase has two independent Q48.16
implementations -- src/word_source/q48_16_words.c (hosted/vendored) and
src/starkernel/math/q48_16.c (kernel-only; the kernel build does not
compile the former at all). The hosted build linked fine after the first
pass; the kernel build failed with undefined references until the same
two functions were added to both .c files and both q48_16.h headers
(include/q48_16.h and include/starkernel/q48_16.h). Not fixed at the root
-- Q.LOG/Q.EXP/Q.SQRT already had this same four-file duplication,
unremarked until now -- just navigated correctly for this item.

Verified live on amd64 via serial injection: sin/cos at 0, +-pi/2, pi, and
3pi (range-reduction across multiple turns) all match expected values
within Taylor-series truncation error (<0.2%).

All three architectures boot clean to ok> with the DoE completing;
dict_hash identical across all three (0x291a660b05fa7b52).

FABRIC.md item 4.3.3a marked done with full acceptance evidence.
This commit is contained in:
Robert Allan James
2026-08-07 13:39:05 -04:00
parent fd1c8ce386
commit 36389e9d4a
8 changed files with 269 additions and 2 deletions
+25 -1
View File
@@ -3728,11 +3728,35 @@ document and committing that amendment as its own item.*
>
> Not wired into `init.4th`'s boot chain, per plan — Console isn't a fleet VM yet.
- [ ] **4.3.3a — Q48.16 trigonometry.** `Q.SIN`/`Q.COS` (radian input) added to `q48_16.c`,
- [x] **4.3.3a — Q48.16 trigonometry.** `Q.SIN`/`Q.COS` (radian input) added to `q48_16.c`,
Taylor series after range-reducing into `[-π, π]` — same pattern as this file's existing
`Q.LOG`/`Q.EXP`/`Q.SQRT`, not a new precedent. Raised 2026-08-07 while scoping 4.3.3: needed
by 4.3.3b, does not exist anywhere in this codebase today (checked). *Refs:* §27.3.
> **Done, 2026-08-07.** `q48_reduce_angle()` (single integer division on the raw Q48.16
> representations to strip full `2·PI_Q48` turns, then a bounded fix-up loop) plus
> `q48_sin_approx`/`q48_cos_approx` (Taylor series, terms `n=3,5,7,9,11` / `n=2,4,6,8,10`,
> early exit below 10). `PI_Q48 = 205887`; `TWO_PI_Q48` is *derived* as `2·PI_Q48` rather
> than independently rounded, so the ±π reduction boundary has no seam.
>
> **A real duplication, not previously flagged:** this codebase has *two* independent
> Q48.16 implementations — `src/word_source/q48_16_words.c` (vendored/hosted) and
> `src/starkernel/math/q48_16.c` (kernel-only; the kernel build does not compile the
> former at all). Found the hard way — the hosted build linked fine, the kernel build
> failed with `undefined reference to q48_sin_approx` until the same two functions were
> added to both files (plus both `q48_16.h` headers — `include/q48_16.h` and
> `include/starkernel/q48_16.h`, which also declare the same functions independently).
> Not fixed at the root (de-duplicating the two implementations is a much larger change
> than this item), just navigated correctly — `Q.LOG`/`Q.EXP`/`Q.SQRT` already had this
> same four-file duplication, unremarked until now.
>
> **Verified live on amd64** via serial injection: `sin(0)=0`, `cos(0)=65536` (exact),
> `sin(π/2)=65536`, `cos(π/2)=0` (exact), `sin(-π/2)=-65536` (exact, confirms the odd-
> function sign handling), `sin(π)≈-27` (residual from `PI_Q48` rounding, ~0.04%),
> `cos(π)≈-65656` (Taylor truncation near the interval edge, ~0.18%), and `sin(3π)` reduces
> to the same `-27` as `sin(π)`, confirming range reduction across multiple turns. Both
> hosted and kernel (amd64) builds clean.
- [ ] **4.3.3b — Geometry drawing primitive wordset.** `LINE`, `CIRCLE`, `ARC`, `ELLIPSE` in
`capsules/fabric.4th`, built on 4.3.3's `PLOT`/`CART-PLOT` and 4.3.3a's `Q.SIN`/`Q.COS`.
Raised 2026-08-07. Q48.16 throughout; resolution-agnostic (48 integer bits comfortably