nn-anatomy

実装メモ (Implementation Notes)

このファイルは v1 完成までの開発記録。プロジェクト紹介・利用案内は ../README.md を参照。設計の全文は design.md、数学リファレンスは math-notes.md、授業進行プランは lesson-plans.md。

大学情報系学部・初学者向けに、ニューラルネットワークの forward / backward / update を ノード 1 つずつの粒度で観察できる GUI シミュレータ。配布物は単一 HTML で、ブラウザで開くだけで動く (v1)。

以下は v1 完成までのフェーズ別ログ + UI/UX 調整の記録。後追いで触る人がコードを読むときの「なぜそうなっているか」の参考。

---

進捗

フェーズ	内容	状態
P0	設計書	完了 (docs/design.md)
P1	純計算 (rng, model, datasets) + NumPy 参照実装 + 数値一致テスト	完了
P2	view.js の静的描画 + Forward 1 回実行 + 式の展開 (Forward 時)	完了
P3	Forward / Backward アニメーション + Backward 式展開	完了
P4	Update / 学習ループ / Loss 曲線	完了
P5	決定境界 / Lesson 定義	完了
P6	単一 HTML への bundle / オフライン検証	完了

P6 で動くもの (P5 に加え):

• tools/bundle.py を追加。src/index.html の <link rel="stylesheet"> と <script type="module" src="./js/controller.js"> を、style.css 本体と src/js/*.js を依存順 (rng → datasets → lessons → model → view → controller) に連結したインラインブロックに差し替えて build/nn_sim.html に書き出す。 外部依存なし (Python 標準ライブラリのみ・CDN 参照なし)。
• バンドラは ES モジュールの import 文を削除し export を剥がす方式。 ファイルをまたぐトップレベル名の衝突は build 時点で検出して中断する (現時点では view.js 側の fmtSigned を fmtSignedShort に改名して回避)。
• できた build/nn_sim.html はサーバ不要。file:// で直接開いて Forward / Backward / Update / Loss / 決定境界 / Lesson1〜Lesson8 まで全機能動作。
• 現状サイズ 約 156 KB (設計書 §10 の 175 KB 目標内。Lesson の初学者向け解説を充実させた結果当初の 150 KB を超えたため、教育的価値を優先して 175 KB に予算を引き上げた)。
• tests/py/test_bundle.py が make bundle 成果物の健全性 (サイズ上限 / 外部参照が残っていない / モジュール順 / 主要な宣言の存在 等) を 7 項目自動チェック。

単一 HTML を生成するには:

make bundle   # → build/nn_sim.html (単一 HTML)

P6 後の追加 (A/B 系)

• A1 CIRCLE データセット: データセットに「円形 2 クラス」を追加。 Noise σ と N を UI から指定でき、設計書 §6.6 / §8 の要請どおり freshDataRng で rngData を毎回サブシードから作り直すので 「同じ seed + 同じ σ → 同じ分布」が保たれる。
• A2 アニメ速度スライダ: Reset ボタン横の Speed スライダで 0 (アニメなし) ～ 3× までリアルタイム切り替え。0× で Forward / Backward の粒と Update パルスを全部スキップするので、Run 時の学習が高速モードになる。
• B3 w / b のダブルクリック編集: ネットワーク図のエッジ (w) または バイアスバッジ (b) をダブルクリックすると prompt() が開き、現在値を 直接書き換えられる (設計書 §8:「わざと大きい値に振る」デモ用)。 編集後は Forward / Backward の結果が陳腐化するので phase を idle に戻し、 決定境界も新しい重みで即再描画。
• B10 Reset to Lesson ボタン: Reset の右隣に追加。選択中の Lesson の 推奨値 (sizes / activation / loss / lr / dataset / seed / initScheme / runN) で UI を上書きしてから rebuild するので、LR をいじりすぎたり w を壊した あとでも 1 クリックでレッスンの初期状態に戻せる。Lesson 未選択 (custom) のときはボタンが無効化される。通常 Reset は「今の UI 値で作り直し」のまま 温存。
• B8 LR 発散時の教育的エラー文言: model.js に isNetDiverged(net) を 追加し、a / z / W / b / dL_* のいずれかに NaN / Inf が現れた時点で 検出。Forward / Backward / Update / 1 Step / Run の直後にこれが真だと、
  • state.diverged = true にして Forward 系ボタンを一斉に disabled
  • Run はその時点で中断 (残りエポックはスキップ)
  • Loss タブを「⚠ 勾配が発散しました」カードで置き換え (原因と対処法を明記)
  • イベントログにも「LR を下げるか Reset / Reset to Lesson で初期化」と教示

  Reset / Reset to Lesson のいずれかを押すと state.diverged が false に 戻り、ボタンも再度使えるようになる。

• B6 手描き 2D 2 クラスデータセット: dataset セレクタに 手描き 2D 2 クラス (DRAW_2D) を追加。これを選ぶと決定境界タブに [-1, 1] × [-1, 1] の キャンバスが出て、
  • 左クリック = 青 (y=0) の点
  • 右クリック または Shift+左クリック = 赤 (y=1) の点

  を置ける。点は state.drawPoints に貯まって通常 Reset では消えず、 そのまま 1 Step / Run で学習できる。Reset to Lesson を押すと明示的に クリアされる (Lesson の想定データと混ざらないように)。 datasets.js 側では BUILTIN.DRAW_2D を deterministic: true, userDrawn: true として登録し、make(_rng, { points }) で渡された点の deep-copy を返す。

• B7 Net の JSON export / import: コントロールバーに Export JSON / Import JSON ボタンを追加。Export は現在のネット (sizes / activations / loss / lr / seed / initScheme / dataset / W / b / drawPoints) を nn-simulator/v1 形式の JSON としてダウンロードする (ファイル名は nn-sim_{sizes}_seed{seed}_{timestamp}.json)。Import は ファイル選択ダイアログを開き、createNet + loadWeights で復元した あと UI フィールドも書き戻す。これにより「学習の途中状態を保存して 別の日に続きから実行」「Lesson7 で収束した状態を配布してみんなで 決定境界を観察」といった授業オペレーションが可能になる。 model.js レベルのラウンドトリップ (snapshot → JSON.stringify → JSON.parse → createNet + loadWeights → forward が一致) は tests/js/test_export_roundtrip.test.mjs で float64 精度まで検証済み。
• Lesson の初学者向け解説強化: src/js/lessons.js の Lesson1〜Lesson8 で、hint と 3 つの checks を「UI のどこを見るか (例: w はエッジ中央、b は青バッジ)」「どう操作するか (例: ダブルクリックで書き換え、Forward → Backward → Update の順に押す)」「数式記号は何を指しているか (例: dL/dw, dL/db, δ, φ’ の意味)」の 3 層構造に書き直した。Lesson セレクタから選んだ瞬間に右パネル「レッスン」タブにそのまま表示される。バンドルサイズは 147 KB → 156 KB に増えたので、サイズ予算 (tools/bundle.py の SIZE_BUDGET_BYTES と tests/py/test_bundle.py のアサート、設計書 §10) を 150 KB → 175 KB に引き上げ。
• C11 式テンプレートの分離: 「式の展開」パネルを組み立てる render* 系ヘルパ (Forward / Backward / Update × {ノード, エッジ, バイアス, 出力層}、3 段テンプレ、注記文、数式 HTML ヘルパ mv/mf/mn/mo/mblock etc.) を src/js/controller.js から src/js/explain.js に切り出し。 controller 側は renderExplain() が ui.explainBody.innerHTML = renderExplainHtml(state) を呼ぶだけの薄いラッパになり、1000 行近く 縮んだ (2193 → 1262 行)。DOM 触りは controller、純 string-building は explain、という責務分離になったので、数式表記を調整したいときに controller のイベント配線を開かずに済む。バンドラの依存順も view.js → explain.js → controller.js に更新済み。

P5 で動くもの (P4 に加え):

• コントロールバー先頭に Lesson セレクタ (Lesson1〜Lesson8) を追加。 選ぶと sizes / activation / loss / lr / dataset / seed / initScheme / runN が一括で適用され、Reset が走る (推奨 seed: Lesson5=42, Lesson7=7 など)。 レイヤー表記 (L1N0 など) と紛れないよう、レッスンは Lesson<n> で統一。
• 右パネルに「決定境界」タブを追加 (2 入力データ専用)。 現在のネットで x1×x2 平面の ŷ を 40×40 セルで評価し、 青 (ŷ≈0) → 白 → 赤 (ŷ≈1) のヒートマップで表示。データ点も重ね描画。 Update / 1 Step / Run のたびに更新される。
• 右パネルに「レッスン」タブを追加。選択中のレッスンの目的と 「このレッスンでチェックすること (3 つ)」を常駐表示。
• 1 入力レッスン用の組み込みデータセットとして LINEAR_1D (y = 2x の 5 点) と SIGMOID_1D (σ(x) の 5 点) を追加。
• Lesson7 (XOR, 2-3-1, sigmoid, seed=7, lr=2.0) を Run すると 「平坦域 → 急降下」の 2 相 loss 曲線と、曲線で分かれる決定境界が見える。

P4 で動くもの (P3 に加え):

• Update ボタンが Backward 後に有効化され、SGD の 1 ステップを実行
• 「1 Step」ボタン: 現在サンプルに対し Forward + Backward + Update を一気に走らせる
• 「Run N」ボタン: 全サンプル平均勾配 (= バッチ勾配) で N エポック学習。 設計書 §6.4 に従い、1 エポック = 1 回の update()。
• Update フェーズでは各エッジの中腹に Δw=−η·dL/dw を、 各バイアス横に Δb=−η·dL/db を 正=青 / 負=赤 で表示
• Update 直後に edge stroke-width を一瞬太らせてから元に戻す 「更新で重みが変わった」粒度のフィードバック (0.3s)
• 右パネル「式の展開」に Update 段 (エッジ/バイアス/ノード) が追加:
  • [段1] Δw = −η·∂L/∂w, w ← w + Δw (一般形)
  • [段2] Δw[x1→h1] = −lr·∂L/∂w[x1→h1] (当てはめ)
  • [段3] 数値展開と old → new の表示
• 右パネル「Loss」タブに累積 loss カーブ (純 SVG、外部ライブラリ不使用)。 Y 軸は 0 起点、X 軸は累積ステップ数

P3 で動くもの (P2 に加え):

• Forward ボタンで入力→出力方向に粒が層ごとに流れるアニメーション
• Backward ボタンが Forward 後に有効化され、出力→入力方向に粒が逆流
• Backward 実行後は各ノード下に δ=dL/dz を、各エッジ中腹に dw=dL/dw を赤字で表示
• バイアスバッジ (b=…) もクリック可能になり、δb=dL/db を表示
• 選択中のノード / エッジ / バイアスに対し、Backward 時は式展開が Backward 版 (出力層・中間層・エッジ・バイアスそれぞれ 3 段式) に切り替わる
• 中間層ノードでは chain rule (Σ_k w · δ) を明示的に展開表示

P2 で動くもの:

• コントロールバー (構成・活性化・損失・lr・seed・init スキーム)
• Reset で再初期化 (seed 入力はここで初めて反映)
• Sample セレクタから XOR/AND/OR の 1 サンプルを選び Forward 実行
• SVG でネットワーク構造・z/a/b/W の値を表示
• ノード or エッジをクリック → 補助パネル「式の展開」に Forward 時の 3 段式 (一般形 → 当てはめ → 数値) を表示
• イベントログに操作履歴を残す

ローカルで動作確認するには:

make serve   # → http://localhost:8000/ でブラウザから開く

開発環境

• uv 0.11+
• Node.js 20+ (v22 系で動作確認)
• モダンブラウザ (P2 以降)

初回:

uv sync              # Python 依存 (numpy, pytest) を .venv に揃える
node --version       # v20 以上であることを確認

テスト実行

make test            # JS + Python の全テストを一括実行
make test-js         # tests/js/*.test.mjs を node --test で
make test-py         # tests/py を uv run pytest で
make fixtures        # tests/fixtures/*.json を NumPy 参照実装から再生成

現時点で Python 16 件 (うち P6 バンドラ 7 件) / JS 55 件 のテストが通っている状態。

ディレクトリ

prompt/              プロジェクト総則 (既存前提)
docs/design.md       設計書 (最新版)
docs/math-notes.md   画面で展開される数式の定義・導出リファレンス
docs/lesson-plans.md Lesson1〜8 を授業で進行する際のプラン
src/js/              JS 純計算 (rng, model, datasets) + view/explain/controller
src/index.html       UI エントリ (P2 以降)
tests/py/            NumPy 参照実装 + pytest
tests/js/            node:test ベースの JS 単体テスト
tests/fixtures/      参照実装が生成する共通フィクスチャ (JSON)
tools/bundle.py      単一 HTML 生成スクリプト (make bundle から呼ばれる)
build/nn_sim.html    配布用単一 HTML (make bundle が生成, .gitignore 対象)
Makefile             開発タスク一覧 (make help)
pyproject.toml       uv が管理する Python 依存

main.py は uv init が残したスキャフォルド。本プロジェクトでは使わないので削除して構わない (権限の都合で自動削除しなかった)。