From 6c5e6908af51633b4b35ff245bbe34232cfb3f90 Mon Sep 17 00:00:00 2001 From: quint-mbbdigital Date: Mon, 10 Aug 2026 15:01:32 -0400 Subject: [PATCH] docs: disambiguate package Level 0 vs schema Level 0/1/2 Clarify that level_0_baseline / level_0_wwpgd (4L/128 packages) are not the same object as wwgpt --level 0 (1x1x64 schema pilots). Class A docs only. --- README.md | 14 ++++++++++++++ level_0_baseline/README.md | 2 ++ level_0_wwpgd/README.md | 2 ++ 3 files changed, 18 insertions(+) diff --git a/README.md b/README.md index 4918e4ce..477b0022 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,20 @@ This repository runs append-only, paired nanoGPT experiments comparing base optimizers with and without the repository's WW-PGD extension. It provides experiment infrastructure and descriptive analysis; it does **not** ship a scaling-law fit, acceleration conclusion, statistical-significance test, or alpha-generalization result. +## Level naming (read this once) + +Three different “Level 0” objects appear in this repository. They are **not** interchangeable. + +| Name | What it is | Typical size / entry | +|---|---|---| +| **Schema / runner Levels 0–2** | `wwgpt` pilot ladder (`--level N`, `configs/level{N}_*.yaml`, `run_one_pair.sh` / multiseed) | **Level 0:** 1 layer · 1 head · width 64 (see config). Levels 1–2 scale up. | +| **`level_0_baseline/`** | Separate **baseline-only** optimizer comparison package (SGD / AdamW / Muon) | **4 layers · 4 heads · width 128** · own scripts/notebooks — see [`level_0_baseline/README.md`](level_0_baseline/README.md) | +| **`level_0_wwpgd/`** | Sibling of the baseline package: same 4L/128 protocol **plus** stock WW-PGD event projection | See [`level_0_wwpgd/README.md`](level_0_wwpgd/README.md) | + +There are also `level_1_baseline/` and `level_1_wwpgd/` packages for the next baseline rung. Those names still mean **package folders**, not `wwgpt --level 1`. + +**Rule of thumb:** if the path is a top-level `level_*_baseline` / `level_*_wwpgd` directory, it is the **package** experiment. If the command is `wwgpt … --level N` or `configs/levelN_*.yaml`, it is the **schema** pilot ladder. + ## Quick start on a local MacBook Run the repository from its checked-out `main` branch and keep the prepared corpus and results under `/tmp`: diff --git a/level_0_baseline/README.md b/level_0_baseline/README.md index 6ce960c6..e064c559 100644 --- a/level_0_baseline/README.md +++ b/level_0_baseline/README.md @@ -1,5 +1,7 @@ # Level Zero nanoGPT optimizer baselines +> **Naming:** This package is **not** the same object as schema/runner `wwgpt --level 0` (1×1×64 pilots under `configs/level0_*.yaml`). See the root [README § Level naming](../README.md#level-naming-read-this-once). + This folder contains the canonical **baseline-only Level Zero experiment** for `CalculatedContent/nanogpt-experiments`. diff --git a/level_0_wwpgd/README.md b/level_0_wwpgd/README.md index ff829b3c..3140ac12 100644 --- a/level_0_wwpgd/README.md +++ b/level_0_wwpgd/README.md @@ -1,5 +1,7 @@ # Isolated Level 0 nanoGPT + WWPGD +> **Naming:** This package pairs with `level_0_baseline` (4L/128). It is **not** schema/runner `wwgpt --level 0`. See the root [README § Level naming](../README.md#level-naming-read-this-once). + This sibling experiment deliberately reuses the exact FineWeb-Edu GPT-2-BPE model, AdamW optimizer, minibatch stream, learning-rate schedule, evaluation probes, checkpoint policy, and WeightWatcher cadence from `level_0_baseline`. The only scientific intervention is a fresh stock WWPGD event projection immediately after each successful AdamW update. ## Frozen paired protocol