Point every loading recipe at the renamed checkpoint

README.md

@@ -70,6 +70,19 @@ variable — whether closing the ring helps at equal parameters — and nothing
 > published so the ring-versus-train comparison can be reproduced, not models to deploy. Each
 > README states which layers could not afford ALS and what that costs.
 
+## Healing status is in the filename
+
+Every checkpoint here is either healed or not, and the two must never be compared to each
+other. The weight file says which:
+
+| Filename | Meaning |
+|---|---|
+| `state_dict_fp16_healed.pt` | compressed, then healed with 60M tokens of forward-KL distillation |
+| `state_dict_fp16_unhealed.pt` | compressed only — a structural control, not a usable model |
+
+Naming both `state_dict_fp16.pt` made the distinction invisible to anyone who downloaded a
+single file, which is exactly the mistake that would corrupt a comparison.
+
 ## ⚠️ These are NOT standard `transformers` checkpoints
 
 `state_dict_fp16.pt` holds **ring cores**, not dense `nn.Linear` weights. Loading requires

llama2-7b/README.md

@@ -27,7 +27,7 @@ boundary bond) plus a 5% sparse residual, then healed with pure knowledge distil
 
 ## ⚠️ This is NOT a standard `transformers` checkpoint
 
-The weight tensors in `state_dict_fp16.pt` are **ring cores**, not dense `nn.Linear` weights —
+The weight tensors in `state_dict_fp16_healed.pt` are **ring cores**, not dense `nn.Linear` weights —
 loading them requires reconstructing the model with the custom `TRLinear`/`SparseAugTRLinear`
 layers from `tensor_formats.py` (included in this repo), using `ranks.json` for the per-layer
 topology. `config.json` is included only as architecture metadata (it is the stock
@@ -45,7 +45,7 @@ from transformers import AutoModelForCausalLM, AutoTokenizer
 REPO = "<your-username>/<this-repo-name>"
 
 ranks = json.loads(open(hf_hub_download(REPO, "ranks.json")).read())
-state_dict_path = hf_hub_download(REPO, "state_dict_fp16.pt")
+state_dict_path = hf_hub_download(REPO, "state_dict_fp16_healed.pt")
 tensor_formats_path = hf_hub_download(REPO, "tensor_formats.py")
 
 # tensor_formats.py has no local package dependencies -- exec it into a namespace
@@ -98,7 +98,7 @@ tok = AutoTokenizer.from_pretrained("NousResearch/Llama-2-7b-chat-hf")
 
 | File | What it is |
 |---|---|
-| `state_dict_fp16.pt` | Healed weights (ring-core form) |
+| `state_dict_fp16_healed.pt` | Healed weights (ring-core form) |
 | `ranks.json` | Per-layer ring topology (output/input mode splits + bond ranks + sparse-residual nnz) |
 | `tensor_formats.py` | `TRLinear`/`SparseAugTRLinear` layer implementations + the ring contraction/fitting code |
 | `config.json` | Stock LLaMA-2-7B-chat architecture config, for reference only |

qwen2.5-3b/README.md

@@ -64,7 +64,7 @@ are aligned by **damage inflicted** rather than by nominal compression rate.
 
 ## ⚠️ This is NOT a standard `transformers` checkpoint
 
-The weight tensors in `state_dict_fp16.pt` are **ring cores**, not dense `nn.Linear` weights.
+The weight tensors in `state_dict_fp16_healed.pt` are **ring cores**, not dense `nn.Linear` weights.
 Loading requires rebuilding the model with the `TRLinear`/`SparseAugTRLinear` layers from
 `tensor_formats.py` (included), using `ranks.json` for the per-layer topology. `config.json` is
 the stock Qwen2.5-3B-Instruct config, included only as architecture metadata — you **cannot**
@@ -115,7 +115,7 @@ for path, spec in ranks.items():
         layer = TRLinear(cores, osp, isp, bias=bias)
     setattr(parent, leaf, layer)
 
-sd = torch.load("state_dict_fp16.pt", map_location="cpu")
+sd = torch.load("state_dict_fp16_healed.pt", map_location="cpu")
 missing, unexpected = m.load_state_dict(sd, strict=False)
 assert not missing and not unexpected, (len(missing), len(unexpected))
 m.eval()

qwen2.5-7b/README.md

@@ -63,7 +63,7 @@ Qwen2.5 architecture is harder to compress than LLaMA-2 (2.0204 vs 0.6915, both
 
 ## ⚠️ This is NOT a standard `transformers` checkpoint
 
-`state_dict_fp16.pt` holds **ring cores**, not dense `nn.Linear` weights. Loading requires
+`state_dict_fp16_healed.pt` holds **ring cores**, not dense `nn.Linear` weights. Loading requires
 rebuilding the architecture with the `TRLinear`/`SparseAugTRLinear` layers from
 `tensor_formats.py` (included), using `ranks.json` for the per-layer topology. `config.json` is
 the stock Qwen2.5-7B-Instruct config, included only as architecture metadata — you **cannot**
@@ -114,7 +114,7 @@ for path, spec in ranks.items():
         layer = TRLinear(cores, osp, isp, bias=bias)
     setattr(parent, leaf, layer)
 
-sd = torch.load("state_dict_fp16.pt", map_location="cpu")
+sd = torch.load("state_dict_fp16_healed.pt", map_location="cpu")
 missing, unexpected = m.load_state_dict(sd, strict=False)
 assert not missing and not unexpected, (len(missing), len(unexpected))
 m.eval()

svd-llm-v2/README.md

@@ -32,7 +32,7 @@ import json
 from lowrank_linear import build, materialize_all
 
 model = build("NousResearch/Llama-2-7b-chat-hf",
-              json.load(open("ranks.json")), "state_dict_fp16.pt",
+              json.load(open("ranks.json")), "state_dict_fp16_healed.pt",
               device="cuda")
 # for generation/eval: fuse the factors first (inference-only)
 materialize_all(model)

svd-llm/README.md

@@ -32,7 +32,7 @@ import json
 from lowrank_linear import build, materialize_all
 
 model = build("NousResearch/Llama-2-7b-chat-hf",
-              json.load(open("ranks.json")), "state_dict_fp16.pt",
+              json.load(open("ranks.json")), "state_dict_fp16_healed.pt",
               device="cuda")
 # for generation/eval: fuse the factors first (inference-only)
 materialize_all(model)

tt3-llama2-7b/README.md

@@ -62,7 +62,7 @@ model = AutoModelForCausalLM.from_pretrained(
     revision="351844e75ed0bcbbe3f10671b3c808d2b83894ee", torch_dtype=torch.float16)
 ranks = json.load(open("ranks.json"))
 # replace each named projection with TRLinear / SparseAugTRLinear built from its spec,
-# then load state_dict_fp16.pt with strict=False and assert 0 missing / 0 unexpected.
+# then load state_dict_fp16_unhealed.pt with strict=False and assert 0 missing / 0 unexpected.
 # For evaluation call materialize_() on every ring layer first -- without it each forward
 # re-contracts the chain and generation is ~100x slower.
 ```

tt3-qwen2.5-3b/README.md

@@ -63,5 +63,5 @@ including which layers skipped ALS and the checkpoint sha256, is in `provenance.
 
 Same recipe as the other tensor directories: rebuild each named projection as
 `TRLinear` / `SparseAugTRLinear` from `tensor_formats.py` using `ranks.json`, **carrying the
-q/k/v bias**, then load `state_dict_fp16.pt` with `strict=False` and assert 0 missing /
+q/k/v bias**, then load `state_dict_fp16_unhealed.pt` with `strict=False` and assert 0 missing /
 0 unexpected. Call `materialize_()` before evaluation.