Verified neural units + tools (neural-ddr)

DBI.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d2b79f7d4faf8495deb2e175dad1dd752b16722bd3e64b2d013d80fe38a49b3
+size 154354

DDR5_units.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0d12c4287f9af7967e266f34b872a7c7e6ae8d88ade42067486c5243f0942976
+size 3077986

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean Byrne (Quazim0t0)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,62 @@
+---
+license: mit
+library_name: pytorch
+tags:
+  - verified-units
+  - neural-memory
+  - ddr5
+  - ecc
+  - retrocomputing
+---
+
+# neural-ddr — verified DDR5 memory-logic units
+
+Small neural nets that **emulate DDR5 memory logic**, each verified **bit-identical
+to a golden reference over its entire finite input domain (N/N)** — the same
+methodology as [neural-aarch64-units](https://huggingface.co/Quazim0t0/neural-aarch64-units).
+
+A dev tool: present DDR5 behaviour (bus encoding, addressing, command decode,
+write-CRC, **on-die ECC**) on a machine that only has DDR3/DDR4. The bytes live in
+the host's real RAM; the neural nets emulate the *logic*.
+
+> **Honest by design:** no capacity or speed is invented. This models the
+> data-path logic; it does not turn DDR3 silicon into DDR5.
+
+## Units
+
+| unit | role | verification |
+|------|------|--------------|
+| `DBI` | data-bus-inversion encode/decode (DDR4/5) | 256/256 · 512/512 |
+| `ADDR_MAP` | address → bank-group/bank/row/column | 4096/4096 |
+| `CMD_DECODE` | control lines → DDR command | 32/32 |
+| `WR_CRC` | write-CRC bit-slice (rippled) | 512/512 |
+| `ODECC` | DDR5 on-die ECC — corrects a single-bit flip | 256/256 · 3328/3328 |
+| `DDR5Bridge` | composes the units over real host RAM | 2048/2048 faults corrected |
+
+## Use
+
+```bash
+pip install torch
+python step1_train_verify.py      # DBI + memory bridge
+python step2to6_train_verify.py   # DDR5 units + ECC-correcting bridge
+```
+
+Weights: `DBI.pt`, `DDR5_units.pt`.
+
+**Create your own verified unit** (template: `neural_ddr/dbi.py`): write the exact
+golden finite function → enumerate the domain (decompose big/linear ones into
+bit/byte slices, see `crc.py`/`ecc.py`) → `common.train` → `common.verify` must be
+bit-exact on 100% of inputs → compose (`ddr5_bridge.py`).
+
+## Citation
+
+```bibtex
+@misc{byrne2026neuralddr,
+  title  = {neural-ddr: Verified DDR5 Memory Logic Units},
+  author = {Byrne, Dean (Quazim0t0)},
+  year   = {2026},
+  howpublished = {\url{https://huggingface.co/Quazim0t0/neural-ddr}}
+}
+```
+
+**Dean Byrne (Quazim0t0)** · 2026

neural_ddr/addr_map.py

@@ -0,0 +1,43 @@
+"""
+Step 2: ADDR_MAP -- physical address -> (rank/bank-group/bank/row/column).
+
+DDR performance depends on which address bits pick the bank vs the row/column,
+because interleaving consecutive addresses across banks/bank-groups exposes
+parallelism. That mapping is a fixed bit-permutation -> a finite function we can
+verify N/N, and it is exactly the kind of per-generation policy the bridge swaps.
+
+Small but representative geometry (12-bit address, 4096 configs):
+  column = 4 bits, bank = 2, bank-group = 2, row = 4
+laid out as an interleave (bank/bg taken from interior bits for parallelism).
+"""
+from __future__ import annotations
+import torch
+from .common import bits_of, int_of, pm
+
+ADDR_BITS = 12
+# output bit index -> which input address bit feeds it (the addressing scheme)
+PERM = [0, 3, 6, 9,   1, 4,   7, 10,   2, 5, 8, 11]   # [col4][bank2][bg2][row4]
+FIELDS = [("col", 4), ("bank", 2), ("bg", 2), ("row", 4)]
+
+
+def golden_map_bits(addr: int) -> list[int]:
+    ib = bits_of(addr, ADDR_BITS)
+    return [ib[PERM[o]] for o in range(ADDR_BITS)]
+
+
+def decode_fields(outbits) -> dict:
+    res, i = {}, 0
+    for name, w in FIELDS:
+        res[name] = int_of(outbits[i:i + w]); i += w
+    return res
+
+
+def domain():
+    X = torch.stack([pm(bits_of(a, ADDR_BITS)) for a in range(2 ** ADDR_BITS)])
+    Y = torch.tensor([[float(b) for b in golden_map_bits(a)] for a in range(2 ** ADDR_BITS)])
+    return X, Y
+
+
+def run(net, addr: int) -> dict:
+    y = (net(pm(bits_of(addr, ADDR_BITS)).unsqueeze(0))[0] > 0).int().tolist()
+    return decode_fields(y)

neural_ddr/bridge.py

@@ -0,0 +1,57 @@
+"""
+The memory bridge: real host RAM as the storage array, DDR bus LOGIC emulated by
+verified neural units.
+
+This is the honest core of the "run it on your old PC" idea. The bytes live in a
+buffer in the machine's actual DDR3/DDR4. Every access is routed through the
+neural DDR units for a CHOSEN generation, so the bridge presents that
+generation's *behavior* over ordinary host memory:
+
+  * DDR3  -> no DBI: bytes drive the bus as-is.
+  * DDR4/5 -> DBI:   the verified neural DBI unit encodes each byte onto the
+                     "bus" (>4 zeros -> invert + flag), so <=4 DQ lines are ever
+                     LOW; reads decode it back, bit-exact.
+
+No capacity or speed is created: this models the data-path logic, it does not
+turn DDR3 into DDR5 silicon.
+"""
+
+from __future__ import annotations
+
+from .dbi import NeuralDBIEncode, NeuralDBIDecode
+
+
+class MemoryBridge:
+    def __init__(self, size: int, enc: NeuralDBIEncode, dec: NeuralDBIDecode,
+                 generation: str = "DDR5"):
+        self.size = size
+        self.enc = enc
+        self.dec = dec
+        self.generation = generation
+        self.dbi = generation in ("DDR4", "DDR5")   # DBI introduced in DDR4
+        # storage in real host RAM: the (possibly DBI-encoded) data byte + flag.
+        self._data = bytearray(size)
+        self._flag = bytearray(size)
+        # bus statistics
+        self.dq_low_total = 0
+        self.transfers = 0
+
+    def write(self, addr: int, value: int) -> None:
+        value &= 0xFF
+        if self.dbi:
+            enc, flag = self.enc.encode(value)       # verified neural unit
+        else:
+            enc, flag = value, 0
+        self._data[addr] = enc
+        self._flag[addr] = flag
+        self.dq_low_total += 8 - bin(enc).count("1")  # DQ lines driven LOW
+        self.transfers += 1
+
+    def read(self, addr: int) -> int:
+        enc, flag = self._data[addr], self._flag[addr]
+        if self.dbi:
+            return self.dec.decode(enc, flag)        # verified neural unit
+        return enc
+
+    def avg_dq_low(self) -> float:
+        return self.dq_low_total / max(1, self.transfers)

neural_ddr/cmd_decode.py

@@ -0,0 +1,37 @@
+"""
+Step 3: CMD_DECODE -- control lines -> DDR command.
+
+A DDR command is a truth table over the control pins (CS_n, ACT_n, and the
+RAS_n/CAS_n/WE_n multiplexed lines). It is a finite function -> N/N verifiable.
+(DDR5 uses a multi-cycle CA encoding; the table here is a compact, self-consistent
+DDR4-style decode that the same unit shape can be retrained to for DDR5.)
+"""
+from __future__ import annotations
+import torch
+from .common import bits_of, int_of, pm
+
+IN, OUT = 5, 4
+CMDS = {"DESELECT": 0, "ACTIVATE": 1, "NOP": 2, "READ": 3, "WRITE": 4,
+        "PRECHARGE": 5, "REFRESH": 6, "MRS": 7, "ZQ": 8}
+NAME = {v: k for k, v in CMDS.items()}
+
+
+def golden_cmd(v: int) -> int:
+    cs, act, ras, cas, we = bits_of(v, 5)          # bit0=CS_n .. bit4=WE_n
+    if cs == 1:
+        return CMDS["DESELECT"]
+    if act == 0:
+        return CMDS["ACTIVATE"]
+    table = {(1, 1, 1): "NOP", (1, 1, 0): "NOP", (1, 0, 1): "READ", (1, 0, 0): "WRITE",
+             (0, 1, 1): "PRECHARGE", (0, 1, 0): "REFRESH", (0, 0, 1): "MRS", (0, 0, 0): "ZQ"}
+    return CMDS[table[(ras, cas, we)]]
+
+
+def domain():
+    X = torch.stack([pm(bits_of(v, IN)) for v in range(2 ** IN)])
+    Y = torch.tensor([[float(b) for b in bits_of(golden_cmd(v), OUT)] for v in range(2 ** IN)])
+    return X, Y
+
+
+def run(net, v: int) -> int:
+    return int_of((net(pm(bits_of(v, IN)).unsqueeze(0))[0] > 0).int().tolist())

neural_ddr/common.py

@@ -0,0 +1,52 @@
+"""Shared helpers: bit<->int, MLP factory, exhaustive verify, trainer."""
+from __future__ import annotations
+import torch
+import torch.nn as nn
+
+DEV = "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def bits_of(v: int, n: int) -> list[int]:
+    return [(v >> k) & 1 for k in range(n)]          # LSB-first
+
+
+def int_of(bits) -> int:
+    return sum((1 << k) for k, b in enumerate(bits) if b > 0)
+
+
+def pm(bits) -> torch.Tensor:
+    return torch.tensor([1.0 if b else -1.0 for b in bits], dtype=torch.float32)
+
+
+def mlp(inp: int, out: int, h: int = 256, layers: int = 2) -> nn.Sequential:
+    mods = [nn.Linear(inp, h), nn.GELU()]
+    for _ in range(layers - 1):
+        mods += [nn.Linear(h, h), nn.GELU()]
+    mods += [nn.Linear(h, out)]
+    return nn.Sequential(*mods)
+
+
+@torch.no_grad()
+def verify(net, X, Ybits) -> tuple[int, int]:
+    net = net.to("cpu")
+    pred = (net(X) > 0).int()
+    ok = (pred == Ybits.int()).all(dim=1).sum().item()
+    return ok, X.shape[0]
+
+
+def train(net, X, Ybits, steps=8000, lr=2e-3, tag="", report=2000):
+    net = net.to(DEV)
+    Xd, Yd = X.to(DEV), Ybits.to(DEV)
+    opt = torch.optim.Adam(net.parameters(), lr=lr)
+    sch = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=steps)
+    lossfn = nn.BCEWithLogitsLoss()
+    for e in range(steps):
+        opt.zero_grad()
+        loss = lossfn(net(Xd), Yd)
+        loss.backward(); opt.step(); sch.step()
+        if e % report == 0 or e == steps - 1:
+            ok, tot = verify(net, X, Ybits); net.to(DEV)
+            print(f"    [{tag}] epoch {e:5d}  loss {loss.item():.2e}  verified {ok}/{tot}")
+            if ok == tot:
+                print(f"    [{tag}] -> N/N"); break
+    return net.to("cpu")

neural_ddr/crc.py

@@ -0,0 +1,60 @@
+"""
+Step 4: WR_CRC -- DDR4/5 write-CRC integrity.
+
+CRC is linear over GF(2), so a full-burst CRC over 64+ bits can never be
+enumerated -- but a single-bit slice can. We verify the CRC BIT-SLICE
+exhaustively (state 8b + data bit -> new state, 512 configs) and ripple it,
+exactly the byte-slice/ripple approach of the neural-aarch64 datapath.
+
+Polynomial is configurable; default 0x07. Swap it to match the target JEDEC spec.
+"""
+from __future__ import annotations
+import torch
+from .common import bits_of, int_of, pm
+
+POLY = 0x07
+IN, OUT = 9, 8
+
+
+def crc_bit(state: int, databit: int) -> int:
+    fb = ((state >> 7) & 1) ^ (databit & 1)
+    ns = (state << 1) & 0xFF
+    if fb:
+        ns ^= POLY
+    return ns & 0xFF
+
+
+def domain():
+    xs, ys = [], []
+    for s in range(256):
+        for d in (0, 1):
+            v = (d << 8) | s                       # bits0-7=state, bit8=databit
+            xs.append(pm(bits_of(v, 9)))
+            ys.append([float(b) for b in bits_of(crc_bit(s, d), 8)])
+    return torch.stack(xs), torch.tensor(ys)
+
+
+def run_bit(net, state: int, databit: int) -> int:
+    v = (databit << 8) | state
+    return int_of((net(pm(bits_of(v, 9)).unsqueeze(0))[0] > 0).int().tolist())
+
+
+def crc_byte(net, state: int, byte: int) -> int:
+    for k in range(7, -1, -1):                     # MSB-first
+        state = run_bit(net, state, (byte >> k) & 1)
+    return state
+
+
+def crc_burst(net, data_bytes, init=0) -> int:
+    s = init
+    for b in data_bytes:
+        s = crc_byte(net, s, b)
+    return s
+
+
+def golden_burst(data_bytes, init=0) -> int:
+    s = init
+    for b in data_bytes:
+        for k in range(7, -1, -1):
+            s = crc_bit(s, (b >> k) & 1)
+    return s

neural_ddr/dbi.py

@@ -0,0 +1,130 @@
+"""
+Step 1 of neural-DDR: the DBI (Data Bus Inversion) unit, verified N/N.
+
+Same methodology as the neural-aarch64 datapath units: DBI is a FIXED finite
+function, so a small MLP can be trained until it is bit-identical to a golden
+reference over its ENTIRE input domain (exhaustive N/N verification).
+
+DBI is a real DDR4/DDR5 feature (absent in DDR3) -- so it is exactly the kind of
+per-generation logic the bridge swaps in/out. On the data bus, DDR reads back
+data over DQ lines that are terminated to a pull-up; a line driven LOW burns
+termination power. DBI_dc reduces that: if a byte has more than four 0-bits,
+invert all eight and flag it, so at most four lines are ever LOW.
+
+  encode(byte) -> 9 bits = [8 encoded data][1 DBI flag]
+      inverted = (number_of_zero_bits(byte) > 4)
+      data_out = ~byte & 0xFF  if inverted else byte    # <=4 zeros afterwards
+      flag     = 1 if inverted else 0
+  decode(data_out, flag) -> byte
+      byte = ~data_out & 0xFF  if flag else data_out
+
+Neither storage nor capacity is invented here: this unit only emulates the
+bus-encoding LOGIC. The bytes themselves live in the host's real RAM (bridge).
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+# ---------- golden reference (the finite function we must match) ----------
+def golden_encode(byte: int) -> tuple[int, int]:
+    zeros = 8 - bin(byte & 0xFF).count("1")
+    if zeros > 4:
+        return (~byte) & 0xFF, 1
+    return byte & 0xFF, 0
+
+
+def golden_decode(data_out: int, flag: int) -> int:
+    return (~data_out) & 0xFF if flag else data_out & 0xFF
+
+
+# ---------- bit <-> tensor helpers (LSB-first, +/-1 encoding) ----------
+def byte_bits(v: int, n: int = 8) -> torch.Tensor:
+    return torch.tensor([1.0 if (v >> k) & 1 else -1.0 for k in range(n)], dtype=torch.float32)
+
+
+def bits_to_int(bits) -> int:
+    return sum((1 << k) for k, b in enumerate(bits) if b > 0)
+
+
+# ---------- the neural units ----------
+class NeuralDBIEncode(nn.Module):
+    """8 data bits -> 9 bits (8 encoded data + 1 DBI flag)."""
+
+    def __init__(self):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(8, 128), nn.GELU(),
+            nn.Linear(128, 128), nn.GELU(),
+            nn.Linear(128, 9),
+        )
+
+    def forward(self, x):
+        return self.net(x)
+
+    @torch.no_grad()
+    def encode(self, byte: int) -> tuple[int, int]:
+        y = (self(byte_bits(byte).unsqueeze(0))[0] > 0).int().tolist()
+        return bits_to_int(y[:8]), int(y[8])
+
+
+class NeuralDBIDecode(nn.Module):
+    """9 bits (8 data + flag) -> 8 recovered data bits."""
+
+    def __init__(self):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(9, 128), nn.GELU(),
+            nn.Linear(128, 128), nn.GELU(),
+            nn.Linear(128, 8),
+        )
+
+    def forward(self, x):
+        return self.net(x)
+
+    @torch.no_grad()
+    def decode(self, data_out: int, flag: int) -> int:
+        inp = torch.cat([byte_bits(data_out), torch.tensor([1.0 if flag else -1.0])]).unsqueeze(0)
+        y = (self(inp)[0] > 0).int().tolist()
+        return bits_to_int(y)
+
+
+# ---------- exhaustive datasets + verification ----------
+def encode_domain():
+    X = torch.stack([byte_bits(b) for b in range(256)])
+    Y = torch.stack([
+        torch.tensor([1.0 if (enc >> k) & 1 else -1.0 for k in range(8)] + [1.0 if fl else -1.0])
+        for enc, fl in (golden_encode(b) for b in range(256))
+    ])
+    return X, Y
+
+
+def decode_domain():
+    X, Y = [], []
+    for data_out in range(256):
+        for flag in (0, 1):
+            X.append(torch.cat([byte_bits(data_out), torch.tensor([1.0 if flag else -1.0])]))
+            b = golden_decode(data_out, flag)
+            Y.append(torch.tensor([1.0 if (b >> k) & 1 else -1.0 for k in range(8)]))
+    return torch.stack(X), torch.stack(Y)
+
+
+@torch.no_grad()
+def verify_encode(unit: NeuralDBIEncode) -> tuple[int, int]:
+    ok = 0
+    for b in range(256):
+        g_enc, g_fl = golden_encode(b)
+        n_enc, n_fl = unit.encode(b)
+        ok += (n_enc == g_enc and n_fl == g_fl)
+    return ok, 256
+
+
+@torch.no_grad()
+def verify_decode(unit: NeuralDBIDecode) -> tuple[int, int]:
+    ok = 0
+    for data_out in range(256):
+        for flag in (0, 1):
+            ok += (unit.decode(data_out, flag) == golden_decode(data_out, flag))
+    return ok, 512

neural_ddr/ddr5_bridge.py

@@ -0,0 +1,38 @@
+"""
+Step 6: DDR5Bridge -- compose the verified units into a DDR5 logical interface
+backed by the host's real RAM.
+
+Write:  byte -> neural ECC parity -> 12-bit codeword stored in host RAM
+Read:   12-bit codeword -> neural ECC decode (corrects a single-bit flip) -> byte
+
+`inject_fault` flips a bit in stored memory to emulate a DRAM disturbance; the
+neural ECC unit corrects it on read. That is the DDR5 on-die-ECC guarantee,
+presented on a machine that need not have DDR5 at all.
+"""
+from __future__ import annotations
+from . import ecc
+
+
+class DDR5Bridge:
+    def __init__(self, size: int, enc_net, dec_net):
+        self.size = size
+        self.enc = enc_net
+        self.dec = dec_net
+        self.mem = [0] * size                     # host RAM: 12-bit ECC codewords
+
+    def write(self, addr: int, byte: int) -> None:
+        byte &= 0xFF
+        par = ecc.enc_run(self.enc, byte)         # verified neural parity
+        d = [(byte >> k) & 1 for k in range(8)]
+        cw = [0] * 12
+        for i, pos in enumerate(ecc.DATA_POS):
+            cw[pos - 1] = d[i]
+        for i, j in enumerate(ecc.PAR_POS):
+            cw[j - 1] = par[i]
+        self.mem[addr] = sum((1 << k) for k, b in enumerate(cw) if b)
+
+    def read(self, addr: int) -> int:
+        return ecc.dec_run(self.dec, self.mem[addr])   # verified neural correct+decode
+
+    def inject_fault(self, addr: int, bitpos: int) -> None:
+        self.mem[addr] ^= (1 << bitpos)           # emulate a single-bit disturbance

neural_ddr/ecc.py

@@ -0,0 +1,92 @@
+"""
+Step 5: ODECC -- DDR5 on-die ECC (the marquee DDR5 feature).
+
+DDR5 adds on-die single-error-correction. We implement a concrete SEC Hamming
+code -- Hamming(12,8): 8 data bits protected by 4 parity bits, correcting any
+single-bit flip in the 12-bit codeword. Real DDR5 protects wider words; the
+logic is identical, just more bits.
+
+Two verified units:
+  ENC : 8 data bits            -> 4 parity bits          (domain 256, N/N)
+  DEC : 12-bit codeword        -> 8 corrected data bits  (all no-error + every
+                                  single-bit flip, 256*13 = 3328 inputs, N/N)
+
+The DEC unit genuinely CORRECTS a flipped bit -- that is what lets the bridge
+present ECC-protected memory over ordinary host RAM.
+"""
+from __future__ import annotations
+import torch
+from .common import bits_of, int_of, pm
+
+DATA_POS = [3, 5, 6, 7, 9, 10, 11, 12]      # 1-indexed Hamming positions
+PAR_POS = [1, 2, 4, 8]
+ENC_IN, ENC_OUT = 8, 4
+DEC_IN, DEC_OUT = 12, 8
+
+
+def encode(data8: int) -> list[int]:
+    d = bits_of(data8, 8)
+    cw = {p: 0 for p in range(1, 13)}
+    for i, pos in enumerate(DATA_POS):
+        cw[pos] = d[i]
+    par = []
+    for j in PAR_POS:
+        p = 0
+        for pos in range(1, 13):
+            if pos in PAR_POS:
+                continue
+            if pos & j:
+                p ^= cw[pos]
+        par.append(p)
+    return par                                   # for positions 1,2,4,8
+
+
+def codeword_int(data8: int) -> int:
+    d = bits_of(data8, 8)
+    par = encode(data8)
+    cw = [0] * 12                                # index k = position k+1
+    for i, pos in enumerate(DATA_POS):
+        cw[pos - 1] = d[i]
+    for i, j in enumerate(PAR_POS):
+        cw[j - 1] = par[i]
+    return int_of(cw)
+
+
+def decode(cw_int: int) -> int:
+    cw = bits_of(cw_int, 12)
+    syn = 0
+    for j in PAR_POS:
+        s = 0
+        for pos in range(1, 13):
+            if pos & j:
+                s ^= cw[pos - 1]
+        if s:
+            syn |= j
+    if 1 <= syn <= 12:
+        cw[syn - 1] ^= 1                          # correct the flipped bit
+    return int_of([cw[pos - 1] for pos in DATA_POS])
+
+
+def enc_domain():
+    X = torch.stack([pm(bits_of(d, 8)) for d in range(256)])
+    Y = torch.tensor([[float(b) for b in encode(d)] for d in range(256)])
+    return X, Y
+
+
+def dec_domain():
+    xs, ys = [], []
+    for d in range(256):
+        base = codeword_int(d)
+        for e in range(13):                      # 0 = no error, 1..12 flip pos e
+            v = base if e == 0 else base ^ (1 << (e - 1))
+            xs.append(pm(bits_of(v, 12)))
+            ys.append([float(b) for b in bits_of(d, 8)])
+    return torch.stack(xs), torch.tensor(ys)
+
+
+def enc_run(net, d: int) -> list[int]:
+    return (net(pm(bits_of(d, 8)).unsqueeze(0))[0] > 0).int().tolist()
+
+
+def dec_run(net, cw_int: int) -> int:
+    return int_of((net(pm(bits_of(cw_int, 12)).unsqueeze(0))[0] > 0).int().tolist())

requirements.txt

@@ -0,0 +1 @@
+torch

step1_train_verify.py

@@ -0,0 +1,95 @@
+"""
+Step 1 for neural-DDR: train + exhaustively verify the DBI units, then prove the
+memory bridge round-trips real data through them.
+
+  (a) encode N/N   -> DBI encode matches golden on all 256 bytes
+  (b) decode N/N   -> DBI decode matches golden on all 512 (data,flag) inputs
+  (c) round-trip   -> bridge stores every byte at many addresses via the neural
+                      units and reads it back bit-exact (data integrity)
+  (d) DBI works    -> DDR4/5 bridge never drives >4 DQ lines LOW; DDR3 does
+  (e) generation   -> same host RAM, DDR3 vs DDR5 behavior, both correct
+"""
+
+import torch
+from neural_ddr.dbi import (
+    NeuralDBIEncode, NeuralDBIDecode, encode_domain, decode_domain,
+    verify_encode, verify_decode,
+)
+from neural_ddr.bridge import MemoryBridge
+
+torch.manual_seed(0)
+dev = "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def train(unit, X, Y, steps=12000, lr=2e-3, tag="", verify=None):
+    X, Y = X.to(dev), Y.to(dev)
+    unit = unit.to(dev)
+    opt = torch.optim.Adam(unit.parameters(), lr=lr)
+    sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=steps)
+    for epoch in range(steps):
+        opt.zero_grad()
+        loss = (torch.tanh(unit(X)) - torch.tanh(Y * 4)).pow(2).mean()
+        loss.backward(); opt.step(); sched.step()
+        if epoch % 2000 == 0 or epoch == steps - 1:
+            n_ok, n_tot = verify(unit.cpu()); unit.to(dev)
+            print(f"    [{tag}] epoch {epoch:5d}  loss {loss.item():.2e}  verified {n_ok}/{n_tot}")
+            if n_ok == n_tot:
+                print(f"    [{tag}] -> full N/N reached")
+                break
+    return unit.cpu()
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("STEP 1  --  neural DBI units + memory bridge")
+    print("=" * 60)
+
+    Xe, Ye = encode_domain()
+    Xd, Yd = decode_domain()
+    print("training DBI encode (8 -> 9):")
+    enc = train(NeuralDBIEncode(), Xe, Ye, tag="enc", verify=verify_encode)
+    print("training DBI decode (9 -> 8):")
+    dec = train(NeuralDBIDecode(), Xd, Yd, tag="dec", verify=verify_decode)
+
+    ne, te = verify_encode(enc)
+    nd, td = verify_decode(dec)
+    print("-" * 60)
+    print(f"(a) DBI encode verified   {ne}/{te}  -> {'PASS' if ne==te else 'FAIL'}")
+    print(f"(b) DBI decode verified   {nd}/{td}  -> {'PASS' if nd==td else 'FAIL'}")
+
+    # (c) round-trip integrity through the bridge (DDR5 mode)
+    N = 4096
+    br5 = MemoryBridge(N, enc, dec, generation="DDR5")
+    bad = 0
+    for a in range(N):
+        v = (a * 37 + 11) & 0xFF
+        br5.write(a, v)
+    for a in range(N):
+        v = (a * 37 + 11) & 0xFF
+        bad += (br5.read(a) != v)
+    print(f"(c) bridge round-trip     {N-bad}/{N} bytes exact  -> {'PASS' if bad==0 else 'FAIL'}")
+
+    # (d) DBI bus effect: DDR5 caps DQ-low at 4/byte; DDR3 does not
+    br3 = MemoryBridge(256, enc, dec, generation="DDR3")
+    worst5 = 0
+    for v in range(256):
+        br5b = MemoryBridge(1, enc, dec, generation="DDR5"); br5b.write(0, v)
+        worst5 = max(worst5, int(br5b.dq_low_total))
+        br3.write(v % 256, v)
+    print(f"(d) DBI bus effect: max DQ-low/byte DDR5={worst5} (<=4?), "
+          f"avg DQ-low DDR3={br3.avg_dq_low():.2f}  -> {'PASS' if worst5<=4 else 'FAIL'}")
+
+    # (e) generation swap over the SAME data, both correct
+    okg = True
+    for gen in ("DDR3", "DDR4", "DDR5"):
+        b = MemoryBridge(256, enc, dec, generation=gen)
+        for v in range(256):
+            b.write(v, v)
+        okg = okg and all(b.read(v) == v for v in range(256))
+    print(f"(e) generation swap DDR3/4/5 all round-trip  -> {'PASS' if okg else 'FAIL'}")
+
+    if ne == te and nd == td:
+        torch.save({"encode": enc.state_dict(), "decode": dec.state_dict(),
+                    "meta": {"unit": "DBI", "encode_verified": f"{ne}/{te}",
+                             "decode_verified": f"{nd}/{td}"}}, "DBI.pt")
+        print("  saved verified unit -> DBI.pt")

step2to6_train_verify.py

@@ -0,0 +1,95 @@
+"""
+Steps 2-6: train + exhaustively verify ADDR_MAP, CMD_DECODE, WR_CRC, ODECC,
+then compose them into a DDR5 bridge that corrects real bit-flips over host RAM.
+"""
+import random
+import torch
+from neural_ddr.common import mlp, train, verify
+from neural_ddr import addr_map, cmd_decode, crc, ecc
+from neural_ddr.ddr5_bridge import DDR5Bridge
+
+torch.manual_seed(0)
+random.seed(0)
+R = {}
+
+print("=" * 62)
+print("STEPS 2-6  --  neural DDR5 units + bridge")
+print("=" * 62)
+
+# ---- Step 2: ADDR_MAP ----
+print("Step 2  ADDR_MAP (12 -> 12):")
+Xa, Ya = addr_map.domain()
+net_addr = train(mlp(12, 12, 256, 2), Xa, Ya, steps=8000, tag="addr")
+R["ADDR_MAP"] = verify(net_addr, Xa, Ya)
+
+# ---- Step 3: CMD_DECODE ----
+print("Step 3  CMD_DECODE (5 -> 4):")
+Xc, Yc = cmd_decode.domain()
+net_cmd = train(mlp(5, 4, 64, 2), Xc, Yc, steps=6000, tag="cmd")
+R["CMD_DECODE"] = verify(net_cmd, Xc, Yc)
+
+# ---- Step 4: WR_CRC (bit-slice) ----
+print("Step 4  WR_CRC bit-slice (9 -> 8):")
+Xr, Yr = crc.domain()
+net_crc = train(mlp(9, 8, 128, 2), Xr, Yr, steps=6000, tag="crc")
+R["WR_CRC"] = verify(net_crc, Xr, Yr)
+
+# ---- Step 5: ODECC (encode + decode/correct) ----
+print("Step 5  ODECC encode (8 -> 4):")
+Xe, Ye = ecc.enc_domain()
+net_enc = train(mlp(8, 4, 256, 3), Xe, Ye, steps=15000, tag="ecc-enc")
+R["ODECC_ENC"] = verify(net_enc, Xe, Ye)
+print("Step 5  ODECC decode/correct (12 -> 8):")
+Xd, Yd = ecc.dec_domain()
+net_dec = train(mlp(12, 8, 512, 3), Xd, Yd, steps=20000, tag="ecc-dec")
+R["ODECC_DEC"] = verify(net_dec, Xd, Yd)
+
+print("-" * 62)
+for name, (ok, tot) in R.items():
+    print(f"  {name:12s} verified {ok}/{tot}  -> {'PASS' if ok == tot else 'FAIL'}")
+
+# ---- behavioural checks ----
+print("-" * 62)
+# CMD_DECODE full table
+cmd_ok = all(cmd_decode.run(net_cmd, v) == cmd_decode.golden_cmd(v) for v in range(32))
+print(f"CMD_DECODE truth table (32/32): {'PASS' if cmd_ok else 'FAIL'}  "
+      f"e.g. 0b00101 -> {cmd_decode.NAME[cmd_decode.run(net_cmd, 0b00101)]}")
+
+# ADDR_MAP sample
+f = addr_map.run(net_addr, 0xABC)
+print(f"ADDR_MAP 0xABC -> col={f['col']} bank={f['bank']} bg={f['bg']} row={f['row']}")
+
+# CRC burst vs golden
+bad = 0
+for _ in range(200):
+    msg = [random.randint(0, 255) for _ in range(8)]
+    bad += (crc.crc_burst(net_crc, msg) != crc.golden_burst(msg))
+print(f"WR_CRC 8-byte bursts (200): {'PASS' if bad == 0 else f'FAIL({bad})'}  "
+      f"(neural ripple == golden CRC)")
+
+# ---- Step 6: DDR5 bridge with real bit-flip correction ----
+N = 2048
+br = DDR5Bridge(N, net_enc, net_dec)
+for a in range(N):
+    br.write(a, (a * 89 + 7) & 0xFF)
+# inject one random single-bit fault per location, then read back
+corrected = 0
+for a in range(N):
+    br.inject_fault(a, random.randint(0, 11))
+    if br.read(a) == ((a * 89 + 7) & 0xFF):
+        corrected += 1
+print(f"DDR5Bridge SEC: {corrected}/{N} bytes correct after a random bit-flip each "
+      f"-> {'PASS' if corrected == N else 'FAIL'}")
+
+allpass = all(ok == tot for ok, tot in R.values()) and cmd_ok and bad == 0 and corrected == N
+print("=" * 62)
+print(f"OVERALL: {'ALL PASS' if allpass else 'some checks failed'}")
+
+if all(ok == tot for ok, tot in R.values()):
+    torch.save({
+        "addr_map": net_addr.state_dict(), "cmd_decode": net_cmd.state_dict(),
+        "wr_crc": net_crc.state_dict(), "odecc_enc": net_enc.state_dict(),
+        "odecc_dec": net_dec.state_dict(),
+        "meta": {k: f"{v[0]}/{v[1]}" for k, v in R.items()},
+    }, "DDR5_units.pt")
+    print("saved verified units -> DDR5_units.pt")