| # 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 | |