# MACROGROK — AGC-Inspired Fixed-Point Macro-Model

Patent Pending — BEL ESPRIT D ACCORD TRUST HOLDINGS INC.

Extremely constrained, narrow-task models for 15-bit / Qm.n environments. Code lives in ROM, state in ~2K erasable words. Every bit is budgeted.

## 1. Model Purpose & Scope

* Single, narrowly defined task: attitude correction, trajectory offset, binary/multi-class decision, low-dimensional control law.
* No general-purpose LM or large feature spaces.
* Input/output dimensions very small (typically ≤ 8–16).

## 2. Numeric Representation

* Word: 15-bit data (modern 16-bit with 1-bit reserved).
* Fixed-point Qm.n (e.g., Q1.14, Q3.12, Q7.8) chosen per variable, scale documented per quantity.
* Double/triple precision only where required.
* Saturation handling: clamp, wrap, or flag — defined per variable.

## 3. Memory Layout

**Erasable (RAM) — ~2K words target:**
State vector, input buffer, accumulators, flags/mode bits, tiny stack.

**Fixed (ROM) — majority:**
Model constants (weights/biases, lookup tables, scale factors), code/macros, pre-computed coefficients. Bank/segment switching optional.

## 4. Core Data Structures

```
STATE  : fixed-point vector (persistent)
INPUT  : fixed-point vector (current observation)
OUTPUT : fixed-point vector or discrete command
ACC    : accumulator(s) — single/double precision
SCALES : constant scale factors
FLAGS  : mode, validity, saturation bits
```

## 5. Macro Routine Categories

`LOAD_INPUT` / `SCALE_INPUT` · `MATVEC_TINY` / `DOT_PRODUCT_FIXED` (unrolled) · `LOOKUP_SEGMENT` / `PIECEWISE_LINEAR` · `ACTIVATE` (clip/ReLU/threshold) · `UPDATE_STATE` · `NORMALIZE`/`RESCALE` · `SATURATE` · `EMIT_OUTPUT`

Macros expand to shifts, adds, MUL16, and table lookups — no floating point.

## 6. Forward Pass

```
1. Acquire and scale input → INPUT
2. Optional tiny feature transform
3. Core block(s) (mat-vec + nonlinearity, macro-expanded)
4. State update (if recurrent)
5. Output scaling + saturation
6. Write command / flags
```

All steps use fixed-point ops and explicit erasable temporaries.

## 7. Initialization

Weights/biases/tables in fixed storage; init routine copies needed values to erasable once. Constants never modified at runtime.

## 8. Executive Wrapper (Optional)

Cyclic/priority executive, ability to skip non-critical sections under pressure, watchdog/validity flags.

## 9. Documentation Requirement

For every variable and macro: Qm.n format, physical units, scale, valid range, overflow behavior, memory location (erasable bank or fixed address).

## 10. Example Skeleton

```
; FIXED (ROM)
WEIGHTS_Q3_12 ...
BIAS_Q3_12 ...
SCALE_IN ...  SCALE_OUT ...

; ERASABLE (RAM)
STATE DS 4 ; Q3.12
INPUT DS 4
OUTPUT DS 2
ACC DS 2 ; double precision

; MACROS
MACRO DOT4 ; 4-element dot
MACRO SAT_Q3_12
MACRO UPDATE_STATE

INFER
    LOAD_INPUT
    SCALE_INPUT
    DOT4 WEIGHTS_Q3_12, INPUT, ACC
    ADD BIAS
    SAT_Q3_12
    UPDATE_STATE
    SCALE_OUTPUT
    STORE OUTPUT
    RETURN
```

## Design Principles

Every bit budgeted — tables + interpolation over general arithmetic — unrolled tiny loops — minimal contiguous mutable state — specialized routine, not general engine.

---

## Fixed-Point Contract (INFER4 Example)

4-input binary decision, Q format per quantity, saturate to 32-bit ACC.

| Symbol | Format | Role | Overflow |
|---|---|---|---|
| `INPUT[4]` | Q1.14 | sensors [-1,1) | clamp |
| `WEIGHTS[4]` | Q1.14 | ROM coefficients | const |
| `BIAS` | Q3.12 | offset | const |
| `ACC` | Q7.24 32-bit | dot accumulator | saturate |
| `STATE` | Q3.12 | smoothed output | clamp |
| `OUTPUT` | Q1.14 | command | clamp |
| `FLAGS` | bits | validity/sat/decision | — |

Q1.14 * Q1.14 → Q2.28 → >>4 → Q3.24 (4 products in 32-bit), >>12 → Q3.12 + `BIAS`.

## Memory Map

```
; FIXED / ROM
WEIGHTS_Q1_14: DC 2458, -1638, 819, 3277
BIAS_Q3_12: DC -256
ALPHA_Q1_14: DC 12288 ; 0.75
ONE_Q1_14: DC 16384
OUT_MIN_Q1_14: DC -16384
OUT_MAX_Q1_14: DC 16383
SCORE_MIN_Q3_12: DC -8192 ; -2.0 Q3.12
SCORE_MAX_Q3_12: DC 8191  ; +2.0

; ERASABLE / RAM
INPUT: DS 4
STATE: DS 1 ; Q3.12
OUTPUT: DS 1
ACC_HI: DS 1 ; 32-bit hi
ACC_LO: DS 1 ; 32-bit lo
TMP0: DS 1
TMP1: DS 1
FLAGS: DS 1
FLAG_VALID=0001  FLAG_SAT=0002  FLAG_POSITIVE=0004
```

## Primitive Macros

See `examples/infer4.asm` for full `CLR_ACC`, `MAC_Q1_14` (preserves `PROD_HI:PROD_LO` before `ADD32`), `ACC_TO_Q3_12`, `SAT_Q3_12`, `DOT4_Q1_14`, `THRESHOLD_Q3_12` (+1.0/-1.0), `UPDATE_STATE_3_4` (`(3*STATE+TARGET)/4`).

## INFER4 Routine

`examples/infer4.asm` — `INFER4: CLR FLAGS → DOT4 → ACC_TO_Q3_12 → ADD BIAS → SAT → THRESHOLD → UPDATE_STATE_3_4 → OUTPUT=STATE → FLAG_VALID → RET`

Simulator: `python src/sim.py` (Q1.14/Q3.12 fixed-point, matches assembly semantics).

## References

[1] Virtual AGC Manual — ibiblio.org/apollo/assembly_language_manual.html
[2] AGC — Wikipedia
[3] Block II: 2048 erasable + 36864 fixed words, 15 data bits + parity