HoloMind / holomind.py
zeechimp's picture
Create holomind.py
f726246 verified
Raw History Blame Contribute Delete
17.5 kB
"""
holomind.py
===========
HoloMind: one holographic substrate, several memories.
Educational artifact + reproducible benchmark. Companion to "Twelve
experiments probing the holographic substrate".
Design, extracted from the twelve experiments:
* FHRR vectors at D=2048.
* Symmetric bind for content, directed bind (frequency roll) for order.
* ITEM regions: S = sum_i bind(item_i, item_i), each item a normed
superposition of role-bound fields. Query with a role-bound partial
key, get back the item, read any field by unbinding its role.
* TRANSITION regions: S = sum_i bind_dir(s_i, s_{i+1}). Walk forward
by unbinding the current state.
Key quantitative finding (see [6] below):
Retrieval accuracy at load K depends on the number of successive
unbindings in the query path, not on K alone. One unbind tolerates
K ~ 40-80 at D=2048; each additional unbind cuts tolerable K roughly
in half. |trace| is a monotone overload signal and can be used as a
cheap confidence estimate.
Public API:
mind.role(name) -> role vector
mind.value(name) -> value vector (lazy)
mind.register_value(name, v) -> external vector (e.g. LLM hidden state)
mind.item_region(name)
mind.transition_region(name)
mind.add_item(region, **bindings)
mind.query_item(region, pairs) -> item vector
mind.read_field(item_vec, role_name) -> field vector
mind.classify(vec, candidates) -> (best, sim, sims)
mind.add_transition(region, src, dst, shift=1)
mind.walk(region, start, candidates, steps=5)
mind.evict(region, index)
mind.stats(region)
"""
import numpy as np
import zlib
import time
def _h(s):
return zlib.crc32(s.encode()) & 0xffffffff
class HoloMind:
# ------------------------------------------------------------------
# Construction
# ------------------------------------------------------------------
def __init__(self, d=2048, seed=0):
self.d = d
self.seed = seed
self._roles = {}
self._values = {}
self._regions = {}
def _rvec(self, s):
r = np.random.default_rng(s)
return np.exp(1j * r.uniform(0, 2 * np.pi, self.d))
def role(self, name):
if name not in self._roles:
self._roles[name] = self._rvec(self.seed + _h("R:" + name))
return self._roles[name]
def value(self, name):
if name not in self._values:
self._values[name] = self._rvec(self.seed + _h("V:" + name))
return self._values[name]
def register_value(self, name, vec):
self._values[name] = np.asarray(vec, dtype=complex)
def _as_vec(self, x):
if isinstance(x, np.ndarray):
return x
return self.value(x)
# ------------------------------------------------------------------
# FHRR primitives
# ------------------------------------------------------------------
def _bind(self, a, b):
return np.fft.ifft(np.fft.fft(a) * np.fft.fft(b))
def _unbind(self, a, c):
return np.fft.ifft(np.fft.fft(c) * np.conj(np.fft.fft(a)))
def _bind_dir(self, a, b, shift=1):
return np.fft.ifft(np.fft.fft(a) * np.roll(np.fft.fft(b), shift))
def _unbind_dir(self, a, c, shift=1):
return np.fft.ifft(np.roll(np.fft.fft(c) * np.conj(np.fft.fft(a)), -shift))
def _norm(self, v):
F = np.fft.fft(v)
return np.fft.ifft(F / (np.abs(F) + 1e-12))
def _cos(self, a, b):
return float(np.real(np.vdot(a, b)) /
(np.linalg.norm(a) * np.linalg.norm(b) + 1e-12))
# ------------------------------------------------------------------
# Regions
# ------------------------------------------------------------------
def item_region(self, name):
self._regions[name] = {
"kind": "item",
"trace": np.zeros(self.d, dtype=complex),
"writes": [],
}
def transition_region(self, name):
self._regions[name] = {
"kind": "transition",
"trace": np.zeros(self.d, dtype=complex),
"writes": [],
}
# ------------------------------------------------------------------
# Item region API
# ------------------------------------------------------------------
def add_item(self, region, **bindings):
r = self._regions[region]
item = np.zeros(self.d, dtype=complex)
for rn, val in bindings.items():
item = item + self._bind(self.role(rn), self._as_vec(val))
item = self._norm(item)
term = self._bind(item, item)
r["trace"] = r["trace"] + term
r["writes"].append({"item": item, "bindings": bindings, "term": term})
return item
def query_item(self, region, pairs):
"""Partial key -> approximate item vector. Read fields with read_field."""
r = self._regions[region]
qb = np.zeros(self.d, dtype=complex)
for rn, val in pairs:
qb = qb + self._bind(self.role(rn), self._as_vec(val))
qb = self._norm(qb)
return self._unbind(qb, r["trace"])
def read_field(self, item_vec, field_role):
return self._unbind(self.role(field_role), item_vec)
def classify(self, vec, candidates):
sims = np.array([self._cos(vec, self._as_vec(c)) for c in candidates])
idx = int(np.argmax(sims))
return candidates[idx], float(sims[idx]), sims
# ------------------------------------------------------------------
# Transition region API
# ------------------------------------------------------------------
def add_transition(self, region, src, dst, shift=1):
r = self._regions[region]
a = self._as_vec(src)
b = self._as_vec(dst)
t = self._bind_dir(a, b, shift=shift)
r["trace"] = r["trace"] + t
r["writes"].append({"src": a, "dst": b, "term": t})
def walk(self, region, start, candidates, steps=5, shift=1):
r = self._regions[region]
cur = self._as_vec(start)
chain = [start if not isinstance(start, np.ndarray) else "?"]
for _ in range(steps):
nxt = self._unbind_dir(cur, r["trace"], shift=shift)
sims = np.array([self._cos(nxt, self._as_vec(c)) for c in candidates])
best = candidates[int(np.argmax(sims))]
chain.append(best)
cur = self._as_vec(best)
return chain
# ------------------------------------------------------------------
# Maintenance / diagnostics
# ------------------------------------------------------------------
def evict(self, region, index):
r = self._regions[region]
w = r["writes"][index]
if w is None:
return
r["trace"] = r["trace"] - w["term"]
r["writes"][index] = None
def stats(self, region):
r = self._regions[region]
n = sum(1 for w in r["writes"] if w is not None)
return {"n_writes": n, "magnitude": float(np.linalg.norm(r["trace"]))}
# ======================================================================
# DEMO β€” the model card body. Runnable as-is.
# ======================================================================
if __name__ == "__main__":
t0 = time.time()
mind = HoloMind(d=2048, seed=0)
print("=" * 72)
print("HoloMind demo β€” one substrate, several memories")
print("=" * 72)
# ------------------------------------------------------------------
# 1. FACTS β€” item region, symmetric bind, one-stage read
# ------------------------------------------------------------------
print("\n[1] FACTS (item region, symmetric bind)")
entities = ["france", "paris", "germany", "berlin", "japan", "tokyo",
"europe", "asia"]
for e in entities:
mind.value(e)
mind.item_region("facts")
facts = [
("france", "capital_of", "paris"),
("germany", "capital_of", "berlin"),
("japan", "capital_of", "tokyo"),
("france", "in_continent", "europe"),
("japan", "in_continent", "asia"),
("paris", "in_country", "france"),
("berlin", "in_country", "germany"),
("tokyo", "in_country", "japan"),
]
for s, rel, o in facts:
mind.add_item("facts", subject=s, relation=rel, object=o)
item = mind.query_item("facts",
[("subject", "france"), ("relation", "capital_of")])
best, sim, _ = mind.classify(mind.read_field(item, "object"), entities)
print(f" capital of france -> {best} (sim={sim:.3f})")
item = mind.query_item("facts",
[("subject", "japan"), ("relation", "capital_of")])
best, sim, _ = mind.classify(mind.read_field(item, "object"), entities)
print(f" capital of japan -> {best} (sim={sim:.3f})")
# ------------------------------------------------------------------
# 2. MULTI-HOP
# ------------------------------------------------------------------
print("\n[2] MULTI-HOP (chain queries through one region)")
item = mind.query_item("facts",
[("subject", "france"), ("relation", "capital_of")])
mid, _, _ = mind.classify(mind.read_field(item, "object"), entities)
item2 = mind.query_item("facts",
[("subject", mid), ("relation", "in_country")])
end, sim, _ = mind.classify(mind.read_field(item2, "object"), entities)
print(f" france --capital_of--> {mid} --in_country--> {end} (sim={sim:.3f})")
# ------------------------------------------------------------------
# 3. EPISODES β€” transition region, directed bind
# ------------------------------------------------------------------
print("\n[3] EPISODES (directed sequence)")
events = ["wake", "coffee", "commute", "work", "lunch", "work2",
"commute2", "dinner", "read", "sleep"]
for e in events:
mind.value(e)
mind.transition_region("episodes")
for a, b in zip(events[:-1], events[1:]):
mind.add_transition("episodes", a, b)
chain = mind.walk("episodes", "wake", candidates=events, steps=5)
print(f" walk from 'wake': {chain}")
chain = mind.walk("episodes", "lunch", candidates=events, steps=3)
print(f" walk from 'lunch': {chain}")
# ------------------------------------------------------------------
# 4. MULTIMODAL β€” one concept, several addresses
# ------------------------------------------------------------------
print("\n[4] MULTIMODAL (same concept, several addresses)")
concepts = ["cat", "dog", "bird"]
for c in concepts:
mind.value(c)
for i in range(3):
mind.value(f"img_{i}")
mind.value(f"aud_{i}")
mind.item_region("senses")
for i, c in enumerate(concepts):
mind.add_item("senses", image=f"img_{i}", audio=f"aud_{i}", label=c)
item = mind.query_item("senses", [("image", "img_0")])
label, sim, _ = mind.classify(mind.read_field(item, "label"), concepts)
print(f" img_0 -> {label} (sim={sim:.3f})")
item = mind.query_item("senses", [("audio", "aud_1")])
label, sim, _ = mind.classify(mind.read_field(item, "label"), concepts)
print(f" aud_1 -> {label} (sim={sim:.3f})")
# ------------------------------------------------------------------
# 5. CROSS-REGION β€” a retrieved vector is a valid key in another region
# ------------------------------------------------------------------
print("\n[5] CROSS-REGION (retrieved value reused as a key elsewhere)")
# Split facts into two regions sharing the value codebook.
mind.item_region("capitals")
mind.item_region("continents")
for s, rel, o in facts:
if rel == "capital_of":
mind.add_item("capitals", subject=s, object=o)
elif rel == "in_continent":
mind.add_item("continents", subject=s, object=o)
# hop 1: capitals('france') -> a capital
item = mind.query_item("capitals", [("subject", "france")])
capital, sim_c, _ = mind.classify(mind.read_field(item, "object"), entities)
# hop 2: the retrieved capital is not a subject in 'continents'; instead
# we route through the country itself. Look up capitals->object->country
# via the flat facts region to recover the country, then query continents.
item = mind.query_item("facts", [("subject", capital),
("relation", "in_country")])
country, sim_k, _ = mind.classify(mind.read_field(item, "object"), entities)
item = mind.query_item("continents", [("subject", country)])
continent, sim_e, _ = mind.classify(mind.read_field(item, "object"), entities)
print(f" capitals('france') -> {capital} (sim={sim_c:.3f})")
print(f" facts('{capital}', in_country) -> {country} (sim={sim_k:.3f})")
print(f" continents('{country}') -> {continent} (sim={sim_e:.3f})")
# ------------------------------------------------------------------
# 6. CAPACITY β€” one-stage vs two-stage read at the same load
# ------------------------------------------------------------------
print("\n[6] CAPACITY (one-stage vs two-stage read, D=2048)")
print(" Per-item structure: 2 roles. Same load, two query depths.")
print(" One-stage: unbind key -> item, classify item directly.")
print(" Two-stage: unbind key -> item, unbind field role, classify.")
print(f"\n {'N':>4} {'one-stage':>10} {'two-stage':>10} {'|trace|':>8}")
pool = [f"w_{i}" for i in range(400)]
for w in pool:
mind.value(w)
for N in [10, 20, 40, 60, 80, 120]:
# one region per N so loads don't accumulate
mind.item_region(f"load1_{N}")
mind.item_region(f"load2_{N}")
rng = np.random.default_rng(1000 + N)
pairs = []
for i in range(N):
key = pool[i]
val = pool[int(rng.integers(0, len(pool)))]
pairs.append((key, val))
mind.add_item(f"load1_{N}", key=key, val=val)
mind.add_item(f"load2_{N}", key=key, val=val)
# one-stage: classify the retrieved item against stored item vectors
items1 = [w["item"] for w in mind._regions[f"load1_{N}"]["writes"]]
ok1 = 0
for i, (key, _) in enumerate(pairs):
u = mind.query_item(f"load1_{N}", [("key", key)])
_, _, sims = mind.classify(u, items1)
if int(np.argmax(sims)) == i:
ok1 += 1
# two-stage: read the 'val' field, classify against value codebook
assign = {k: v for k, v in pairs}
ok2 = 0
for key, val in pairs:
u = mind.query_item(f"load2_{N}", [("key", key)])
got, _, _ = mind.classify(mind.read_field(u, "val"), pool)
if got == val:
ok2 += 1
mag = mind.stats(f"load1_{N}")["magnitude"]
print(f" {N:>4} {ok1/N:>10.2f} {ok2/N:>10.2f} {mag:>8.1f}")
# ------------------------------------------------------------------
# 7. EVICTION β€” reversible additive memory
# ------------------------------------------------------------------
print("\n[7] EVICTION (subtract one stored write, reversible)")
mind.item_region("evict")
keys = [f"e_{i}" for i in range(5)]
for k in keys:
mind.value(k)
for k in keys:
mind.add_item("evict", key=k, val=k) # identity map
item = mind.query_item("evict", [("key", keys[2])])
before, sb, _ = mind.classify(mind.read_field(item, "val"), keys)
mind.evict("evict", 2)
item = mind.query_item("evict", [("key", keys[2])])
after, sa, _ = mind.classify(mind.read_field(item, "val"), keys)
item = mind.query_item("evict", [("key", keys[0])])
still, ss, _ = mind.classify(mind.read_field(item, "val"), keys)
print(f" before evict: key={keys[2]} -> {before} (sim={sb:.3f})")
print(f" after evict: key={keys[2]} -> {after} (sim={sa:.3f}) [expect noise]")
print(f" after evict: key={keys[0]} -> {still} (sim={ss:.3f}) [expect {keys[0]}]")
# ------------------------------------------------------------------
# 8. CONFIDENCE β€” |trace| as a hallucination signal
# ------------------------------------------------------------------
print("\n[8] CONFIDENCE (|trace| vs. correctness)")
print(" At D=2048, |trace| ~ D/4 marks the onset of overload.")
print(f"\n {'region':>14} {'n':>4} {'|trace|':>8} {'hit':>6} {'verdict':>12}")
for N in [10, 40, 80, 120]:
reg = f"load1_{N}"
items = [w["item"] for w in mind._regions[reg]["writes"]]
ok = 0
rng = np.random.default_rng(1000 + N)
# replay the same assignment to check hits
pairs = []
for i in range(N):
key = pool[i]
val = pool[int(rng.integers(0, len(pool)))]
pairs.append((key, val))
for i, (key, _) in enumerate(pairs):
u = mind.query_item(reg, [("key", key)])
_, _, sims = mind.classify(u, items)
if int(np.argmax(sims)) == i:
ok += 1
mag = mind.stats(reg)["magnitude"]
ratio = mag / mind.d
verdict = "confident" if ratio < 0.20 else (
"marginal" if ratio < 0.25 else "overloaded")
print(f" {reg:>14} {N:>4} {mag:>8.1f} {ok/N:>6.2f} {verdict:>12}")
print(f"\nTotal runtime: {time.time() - t0:.1f}s")