BSC 專題課程 / 蕈狀體學 21 點 / PART 6

PART 6

讀程式:兩個指令按下去,電腦做了哪些事

從 run_all.sh 那一支腳本開始,順著「誰叫了誰」讀三層:你親手執行的兩支腳本、它們叫到的六支 Python 程式、以及模型本身的兩個檔。每一段在做什麼、為什麼要有這一段;不教 Python 語法。讀完,PART 1 的四個零件(連結體、神經元方程式、輸入編碼、讀出規則)與學習規則各在哪個檔、哪幾行就對得上

← PART 5 逐手看蕈狀體怎麼打 回課程首頁 →

1怎麼讀這一頁:三層、標記、先認識幾個詞

PART 2 要你在終端機(打字下指令的視窗)貼兩個指令:bash setup_envs.sh 建環境,bash blackjack/run_all.sh 一鍵重跑。這一頁回答一個問題:那兩個指令按下去之後,電腦到底做了哪些事?做法是順著「誰叫了誰」往下讀,分三層:

層是什麼檔案在本頁哪一節
第一層你親手執行的兩支 shell script(一個文字檔,裡面是一行一行要在終端機裡執行的指令)setup_envs.sh、run_all.sh第 2 節
第二層run_all.sh 每一行叫到的 Python 程式。兩支是作者的(下載資料、切出蕈狀體),四支是本課寫的(打 21 點、評分作者的大腦檔、四項檢查、驗收)作者的:fetch.py、extract.py;我們的:bj2_blackjack.py、bj3_author_brain.py、bj_extra.py、check.py第 3 到 5 節
第三層第二層的程式再往下引用的檔案:模型本身。蕈狀體一個檔,21 點一個檔model.py、blackjack.py第 6、7 節

第二層讀完,你就知道每一步「叫了哪個模型、餵了什麼、把結果寫到哪」;模型裡面怎麼算,在第三層。再往下的第三方套件(別人寫好、裝進來直接用的程式庫,例如 numpy)不展開,只在被叫到的那一行說它做什麼(第 8 節)。

先認識幾個詞

下面每一段都會用到這些詞,先在這裡說一次,之後不再解釋。

程式區塊怎麼看

每一段程式都照同一個格式:先用一段話說這段在做什麼、為什麼要有這一段,然後放程式,程式下面逐行解釋。程式區塊左邊的數字是原檔的行號,和你下載下來的檔案完全一致;底色標出的行是接下來要講的行;行號旁的 ①②③ 是解釋裡用的標記。下面拿 run_all.sh 的兩行當例子:

  6①PY="$(conda info --base)/envs/flyplay_bj/bin/python"  7②export PYTHONNOUSERSITE=1 PYTHONPATH=.
下載包的 blackjack/run_all.sh 第 6–7 行

哪些檔案、各有幾行

本課自己寫的六個檔案在下載包裡;作者的檔案是 MIT 授權,run_all.sh 第一次跑會把整個 repo 放在 blackjack/repo/。兩邊都只放講到的段落,沒講到的行跳過(行號照原檔,缺的行可以打開檔案對照)。

setup_envs.sh第一層 我們的 11 行

建一個 conda 環境

run_all.sh第一層 我們的 18 行

一鍵重跑:取得程式與資料、BJ1 到 BJ3、X1 到 X4、驗收

fetch.py第二層 作者的 189 行

BJ1:下載 MaleCNS 的連結矩陣、核對八個計數

extract.py第二層 作者的 140 行

BJ1:切出蕈狀體四群、算 MBON 的趨近/迴避標記

bj2_blackjack.py第二層 我們的 47 行

BJ2:四個條件 × 3 個種子 × 30,000 手

bj3_author_brain.py第二層 我們的 28 行

BJ3:把作者附的大腦檔載入 Python 模型重新評分

bj_extra.py第二層 我們的 132 行

X1 到 X4,都在 21 點上做

check.py第二層 我們的 63 行

驗收:你的結果對本課實跑的結果

model.py第三層 作者的 153 行

蕈狀體:KC 的稀疏代碼、MBON、好惡值、學習規則

blackjack.py第三層 作者的 295 行

21 點:規則、牌面怎麼編成氣味、怎麼選動作、怎麼學

行數由 scripts/make_code.py 數出,記在 out/code_meta.json。本頁每一個程式區塊都由同一支程式從原檔照抄,make_code.py --check 會逐塊確認和原檔一致。make_code.py 是做這個網頁用的工具,放在課程網站的程式倉庫,不在下載包裡,run_all.sh 不會叫它。

不會 Python 也讀得下去。會用到的語法只有幾種:變數(給東西取名)、函式(把幾行打包、取名、之後可以重複叫)、迴圈(同一段程式對一串東西各做一次)、條件(如果…就…)、串列與字典(一串值;一組「名字→值」)、類別與物件(上面詞表)。每一種第一次出現時就地解釋,之後不再解釋。

2第一層:兩支 shell script

setup_envs.sh:建一個環境

這支在做什麼。PART 2 第 4 節說過,fly-blackjack 只用三個套件、彼此不衝突,所以一個環境就夠;但套件版本要固定成本課實跑時的版本,對不上時才知道差在哪裡。這支腳本就做這一件事。

  1 #!/usr/bin/env bash
  2 # 建立重現 fly-blackjack 需要的一個 conda 環境(只需做一次,需要網路)。用法:bash setup_envs.sh
  3 # 版本照本課實跑時的環境固定。
  4①set -e  5②CONDA_BASE="$(conda info --base)"  6③export PYTHONNOUSERSITE=1        # 不讓使用者家目錄 ~/.local 裡的套件混進環境
下載包的 setup_envs.sh 第 1–6 行
  7 # conda 預設的 libmamba 求解器在某些安裝裡會壞掉(錯誤訊息含 libmambapy),失敗時改用 classic 求解器再試一次
  8①mk() { conda env list | grep -q "^$1 " || conda create -y -q -n "$1" "python=$2" || conda create -y -q --solver classic -n "$1" "python=$2"  9②       "$CONDA_BASE/envs/$1/bin/pip" install -q "${@:3}"; }
下載包的 setup_envs.sh 第 7–9 行
 10①mk flyplay_bj  3.11 numpy==2.4.6 scipy==1.17.1 pandas==3.0.6 11②for e in flyplay_bj; do "$CONDA_BASE/envs/$e/bin/python" -c "import sys; print('$e', sys.version.split()[0], 'OK')"; done
下載包的 setup_envs.sh 第 10–11 行

run_all.sh:一鍵重跑

這支在做什麼。它就是 PART 3 的 BJ1 到 BJ3 與 PART 4 的 X1 到 X4 排成一列,最後驗收。讀它的重點不是指令本身,而是每一步叫哪支程式、輸出寫到哪裡;第二層要讀的程式,就是這支腳本一行一行叫出來的。

  1 #!/usr/bin/env bash
  2 # fly-blackjack 的 21 點實驗一鍵重跑:BJ1–BJ3 + 加做檢查 X1–X4。用法:bash run_all.sh(本課實測時間見 PART 2)
  3 # 需要先跑過上一層的 setup_envs.sh。每步的終端輸出寫到 logs/,數字寫到 results/,最後由 ../check.py 驗收。
  4①set -eo pipefail  5②HERE="$(cd "$(dirname "$0")" && pwd)"  6 PY="$(conda info --base)/envs/flyplay_bj/bin/python"
  7 export PYTHONNOUSERSITE=1 PYTHONPATH=.
  8③cd "$HERE"
下載包的 blackjack/run_all.sh 第 1–8 行
  9①[ -d repo ] || git clone -q https://github.com/WilliamJones/fly-blackjack.git repo 10②git -C repo checkout -q 004b2e3e9ccb742f83c5bdc2717c97f5a64b420f 11③mkdir -p logs results 12④cd repo
下載包的 blackjack/run_all.sh 第 9–12 行

這段在做什麼。把作者的程式拿到手,並固定版本。下載包不附作者的程式(原因見 PART 2 第 3 節:讓你跑到的一定是 GitHub 上的那一份),所以是你的電腦自己去 GitHub 取。

 13①echo "BJ1 下載並切出蕈狀體(下載約 107 MB)"; $PY -m flybrain.mb.fetch > ../logs/bj1_fetch.log 2>&1 14②for i in 1 2; do $PY -m flybrain.mb.extract > ../logs/bj1_extract_run$i.log 2>&1; md5sum data/mb_circuit.npz; done | tee ../logs/bj1_md5.txt 15③echo "BJ2 21 點 30,000 手 × 4 個條件 × 3 個種子"; $PY ../scripts/bj2_blackjack.py 30000 0 1 2 > ../logs/bj2_blackjack.log 2>&1 16④echo "BJ3 評分作者附的大腦";     $PY ../scripts/bj3_author_brain.py > ../logs/bj3_author_brain.log 2>&1 17⑤echo "加做檢查 X1–X4";            $PY ../scripts/bj_extra.py > ../logs/bj_extra.log 2>&1 18⑥cd "$HERE"; "$PY" ../check.py blackjack
下載包的 blackjack/run_all.sh 第 13–18 行

這段在做什麼。五個步驟、六行:BJ1 佔兩行(下載、切兩次並比 md5),BJ2、BJ3、X1–X4、驗收各一行。格式都一樣:echo 印出步驟名,然後用環境裡的 Python 跑一支程式,> 把它印出來的東西存進 logs/ 的一個檔案(2>&1 是把錯誤訊息也存進同一個檔)。PART 3 每一節末尾的終端機節錄,就是這些 log 檔的原文。BJ1 直接用作者的程式($PY -m 執行作者的模組);BJ2 以後跑我們自己寫的程式,原因在 PART 3 第 2 節:21 點實驗作者沒有留下可以直接在終端機打的指令,他是在 Python 裡呼叫函式跑的,所以本課寫了小程式去呼叫作者的函式,不改作者任何一行。這些程式放在 blackjack/scripts/,從 repo/ 看過去是 ../scripts/。

讀到這裡你已經有第二層的目錄。run_all.sh 總共叫了六支 Python 程式:作者的 fetch.py、extract.py,我們的 bj2_blackjack.py、bj3_author_brain.py、bj_extra.py、check.py。下面三節照這個順序讀。

3第二層:BJ1,作者的 fetch.py 與 extract.py

這兩支是「有命令列入口」的作者程式(命令列:你在終端機打的那一行,程式名後面跟的字;本頁一律叫命令列):檔案最後一段寫著 if __name__ == "__main__":,意思是「這個檔被直接執行(而不是被別人匯入)時,做下面這些事」。run_all.sh 的 -m 就是從那一段進去。每一支的順序都一樣:先看入口那一段知道它收什麼設定,再往上看被叫到的函式。

fetch.py:下載連結矩陣並核對

這支在做什麼。PART 2 第 5 節講的資料固定方式:不是固定版本號,而是下載完核對檔案大小、載入後核對八個計數,有一個不同就停下來。這支程式就是那段話。

 14①BASE = ("https://raw.githubusercontent.com/YijieYin/connectome_data_prep/" 15         "main/data/maleCNS/") 16②FILES = { 17     "mcns_syncount_all_neuron.npz": 78_770_675, 18     "mcns_all_neuron_meta.csv": 28_023_979, 19 }
 20③DATA = Path("data/malecns") 21 
 22④EXPECTED = { 23     "neurons": 161_429, 24     "connections": 25_083_972, 25     "synapses": 121_933_227, 26     "kenyon_cells": 4_064, 27     "mbons": 97, 28     "pam": 316, 29     "ppl1": 16, 30     "projection_neurons": 682, 31 }
fly-blackjack 的 flybrain/mb/fetch.py 第 14–31 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
134 def download(force: bool = False) -> Path:135     DATA.mkdir(parents=True, exist_ok=True)
136①    for name, size in FILES.items():137         target = DATA / name138         if force and target.exists():
139             target.unlink()
140②        if target.exists() and target.stat().st_size == size:141             print(f"  have {name} ({size/1e6:.0f} MB)")142             continue
143③        _fetch_one(BASE + name, target, size)144         print(f"  got {name} ({target.stat().st_size/1e6:.0f} MB)")
145     return DATA
fly-blackjack 的 flybrain/mb/fetch.py 第 134–145 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
162 def verify(quiet: bool = False) -> bool:163     import numpy as np
164①    M, meta = load()165②    t = meta["type"].fillna("")166     got = {167③        "neurons": M.shape[0],168         "connections": M.nnz,169         "synapses": int(M.sum()),170④        "kenyon_cells": int(t.str.match(r"^KC").sum()),171⑤        "mbons": int(t.str.match(r"^MBON").sum()),172         "pam": int(t.str.match(r"^PAM").sum()),173         "ppl1": int(t.str.match(r"^PPL1").sum()),174⑥        "projection_neurons": int((meta["class"].fillna("") == "ALPN").sum()),175     }
fly-blackjack 的 flybrain/mb/fetch.py 第 162–175 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。八個計數怎麼算出來。這裡第一次看到連結矩陣長什麼樣。

177①    for key, want in EXPECTED.items():178         good = got[key] == want179②        ok &= good180         if not quiet:
181             print(f"  {'ok ' if good else 'BAD'} {key:20s} {got[key]:>12,}"182                   + ("" if good else f"   expected {want:,}"))
183     return bool(ok)
184 
185 
186 if __name__ == "__main__":187③    download(force="--force" in sys.argv)188     print("\nverifying:")189④    sys.exit(0 if verify() else 1)
fly-blackjack 的 flybrain/mb/fetch.py 第 177–189 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

extract.py:切出蕈狀體

這支在做什麼。PART 1 第 2 節的那段:從 MaleCNS 切出 PN、KC、MBON、DAN 四群,留四層連結(PN→KC、KC→MBON、DAN→MBON、MBON→MBON;這裡的「層」是 PART 1 的用法:從一群神經元到一群神經元的全部連結,和本頁讀程式分的「三層」是兩回事),KC 只取「路徑上」(同時接到 PN、又連到 MBON)的 3,811 顆中的 1,200 顆;順手替每顆 MBON 算出趨近/迴避標記(PART 1 第 4 節)。

 42①def extract(kenyon: int | None = 1200, seed: int = 20260913): 43②    M, meta = load() 44     t = meta["type"].fillna("") 45     cls = meta["class"].fillna("") 46③    where = lambda pat: meta.index[t.str.match(pat, na=False)].to_numpy() 47 
 48④    PN = meta.index[cls == "ALPN"].to_numpy() 49⑤    KC_all = where(r"^KC") 50     MBON = where(r"^MBON") 51     PAM, PPL1 = where(r"^PAM"), where(r"^PPL1")
fly-blackjack 的 flybrain/mb/extract.py 第 42–51 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
 53     # keep only Kenyon cells that actually sit on the pathway
 54①    pn_in = np.asarray(M[PN][:, KC_all].sum(axis=0)).ravel() 55②    mbon_out = np.asarray(M[KC_all][:, MBON].sum(axis=1)).ravel() 56③    live = (pn_in > 0) & (mbon_out > 0) 57     KC = KC_all[live] 58④    if kenyon and kenyon < len(KC): 59         # Rank by total pathway involvement, then take an evenly spaced sample so
 60         # the subset spans the range rather than only the most connected cells.
 61         # kind="stable" matters: most Kenyon cells tie on this score, and an
 62         # unstable sort orders ties differently between numpy versions, which
 63         # silently gives different machines a different subset of cells.
 64⑤        order = np.argsort(-(pn_in[live] + mbon_out[live]), kind="stable") 65⑥        KC = KC[np.sort(order[np.linspace(0, len(order) - 1, kenyon).astype(int)])]
fly-blackjack 的 flybrain/mb/extract.py 第 53–65 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。PART 1 說「KC 只留同時接到 PN、又連到 MBON 的 3,811 顆,再依排名等距取 1,200 顆」,就是這十三行。

 67①    DAN = np.concatenate([PAM, PPL1]) 68②    blocks = { 69         "pn_kc": M[PN][:, KC], 70         "kc_mbon": M[KC][:, MBON], 71         "dan_mbon": M[DAN][:, MBON], 72         "mbon_mbon": M[MBON][:, MBON], 73     }
 74 
 75③    pam_drive = np.asarray(M[PAM][:, MBON].sum(axis=0)).ravel() 76     ppl_drive = np.asarray(M[PPL1][:, MBON].sum(axis=0)).ravel() 77     # +1 approach-driving (punishment compartment), -1 avoidance-driving (reward)
 78④    valence = np.where(ppl_drive > pam_drive, 1, -1) 79⑤    valence[(pam_drive == 0) & (ppl_drive == 0)] = 0
fly-blackjack 的 flybrain/mb/extract.py 第 67–79 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
 99①def save(blocks, info, path="data/mb_circuit.npz", manifest="data/mb_manifest.json"):100     Path(path).parent.mkdir(parents=True, exist_ok=True)
101     arrays = {}102②    for name, block in blocks.items():103③        coo = block.tocoo()104         arrays[f"{name}_row"] = coo.row.astype(np.int32)105         arrays[f"{name}_col"] = coo.col.astype(np.int32)106         arrays[f"{name}_val"] = coo.data.astype(np.float32)107         arrays[f"{name}_shape"] = np.array(block.shape, np.int32)108④    arrays["mbon_valence"] = np.array(info["mbon_valence"], np.int8)109     arrays["dan_is_punishment"] = np.array(info["dan_is_punishment"], np.int8)110⑤    np.savez_compressed(path, **arrays)
fly-blackjack 的 flybrain/mb/extract.py 第 99–110 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
112①    counts = {k: len(v) for k, v in info["populations"].items()}113     man = dict(114         dataset="MaleCNS v1.0 (Berg et al. 2025 / Nern et al. 2024), CC BY 4.0",
115         mirror="github.com/YijieYin/connectome_data_prep",
116②        counts=counts,117③        edges={k: int(b.nnz) for k, b in blocks.items()},118         synapses={k: int(b.sum()) for k, b in blocks.items()},119④        mbon_approach=int(sum(1 for v in info["mbon_valence"] if v > 0)),120         mbon_avoid=int(sum(1 for v in info["mbon_valence"] if v < 0)),121         selection="ALPN by class; KCs with both ALPN input and MBON output, "
122                   "evenly sampled across pathway-involvement rank; all MBONs; "
123                   "all PAM+PPL1. KC->KC excluded (see extract.py). "
124                   "No behavioural measure used at any point.",
125     )
126⑤    Path(manifest).write_text(json.dumps(man, indent=2))127⑥    Path("data/mb_cells.json").write_text(json.dumps(128         {k: info[k] for k in ("types", "soma", "nt", "mbon_valence", "dan_is_punishment")},129         separators=(",", ":")))130     return man
fly-blackjack 的 flybrain/mb/extract.py 第 112–130 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
133 if __name__ == "__main__":
134     p = argparse.ArgumentParser()
135①    p.add_argument("--kenyon", default="1200", help="number of Kenyon cells, or 'all'")136     a = p.parse_args()
137     n = None if a.kenyon == "all" else int(a.kenyon)138②    blocks, info = extract(kenyon=n)139③    man = save(blocks, info)140④    print(json.dumps(man, indent=2))
fly-blackjack 的 flybrain/mb/extract.py 第 133–140 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

4第二層:BJ2、BJ3 與 X1 到 X4,我們的三支程式

這三支都在下載包的 blackjack/scripts/。共同原則寫在 PART 3 第 2 節:只匯入作者的函式,不修改它;結果寫到 ../results/,不碰作者的 data/。前兩支很短,因為工作只是「照作者在註解裡寫的設定,把他的函式叫一遍,然後把數字存下來」;第三支要換電路、打亂接線,長一點。

bj2_blackjack.py:BJ2,21 點

這支在做什麼。PART 3 第 4 節:四個條件 × 3 個種子 × 30,000 手,設定照作者寫在 blackjack.py 檔尾的註解。21 點本身的規則、牌面怎麼編成氣味、怎麼選動作、怎麼學,全部在作者的 blackjack.py(第 7 節);這支只負責排條件、跑、記數字。

  1 """BJ2:21 點。blackjack.py 沒有命令列入口,依其檔尾 RESULT 註解的設定重跑:
  2 3 種子 × 30,000 手,四個條件,對照組先跑。在 repo/ 目錄下以 PYTHONPATH=. 執行。
  3 用法:python bj2_blackjack.py [hands] [seeds...]"""
  4 import json, sys, time  5 import numpy as np  6①from flybrain.mb.blackjack import FlyPlayer, session, reference_winrates, chart_cells, basic_strategy, HIT, STAND, DOUBLE  7 
  8②HANDS = int(sys.argv[1]) if len(sys.argv) > 1 else 30000  9③SEEDS = [int(s) for s in sys.argv[2:]] or [0, 1, 2] 10④CONDS = [  # 註解中的順序:對照組先跑 11⑤    ("untrained greedy", dict(learn=False, explore=0.0, explore_floor=0.0)), 12⑥    ("no learning + exploration decay", dict(learn=False)), 13⑦    ("dopamine cut + exploration decay", dict(dopamine=False)), 14⑧    ("connectome + dopamine", dict()), 15 ]
下載包的 blackjack/scripts/bj2_blackjack.py 第 1–15 行
 18①def spot_counts(fly): 19     """訓練後 greedy 在 260 格的選擇:hit / stand / double 各幾格。"""
 20     c = {HIT: 0, STAND: 0, DOUBLE: 0} 21②    for (t, soft, up) in chart_cells(): 22③        c[fly.greedy(t, soft, up, True, [HIT, STAND, DOUBLE])] += 1 23     out = {"hit": c[HIT], "stand": c[STAND], "double": c[DOUBLE]} 24     # 依基本策略分類:圖表說該 hit/stand/double 的格子裡,蒼蠅選對幾格(作者稱 double 0/39)
 25     for want_a, nm in [(HIT, "hit"), (STAND, "stand"), (DOUBLE, "double")]: 26④        cells = [(t, s, u) for (t, s, u) in chart_cells() if basic_strategy(t, s, u, True) == want_a] 27         out[f"chart_{nm}_cells"] = len(cells) 28⑤        out[f"chart_{nm}_matched"] = sum(fly.greedy(t, s, u, True, [HIT, STAND, DOUBLE]) == want_a for (t, s, u) in cells) 29     return out
下載包的 blackjack/scripts/bj2_blackjack.py 第 18–29 行

這段在做什麼。PART 3 第 4 節那張「260 格裡的選擇」表(要牌幾格、停牌幾格、加倍幾格)是這裡數的。

 32 out = {"hands": HANDS, "seeds": SEEDS, "conditions": {}} 33①for name, kw in CONDS: 34     runs = []
 35②    for s in SEEDS: 36         t0 = time.time()
 37③        fly = FlyPlayer(seed=s, **kw) 38④        nets, blocks, agree = session(fly, hands=HANDS, seed=s) 39⑤        runs.append(dict(seed=s, first_block=blocks[0], last_block=blocks[-1], agree_first=agree[0], 40                          agree_last=agree[-1], blocks=blocks, agree=agree, spots=spot_counts(fly)))
 41⑥        print(f"{name:34s} seed {s}  winrate {blocks[0]:+.3f} -> {blocks[-1]:+.3f}  " 42               f"agree {agree[0]:.3f} -> {agree[-1]:.3f}  spots {runs[-1]['spots']}  ({time.time() - t0:.0f}s)", flush=True)
 43⑦    out["conditions"][name] = dict(runs=runs, mean_last=float(np.mean([r["last_block"] for r in runs])), 44                                    mean_agree_last=float(np.mean([r["agree_last"] for r in runs]))) 45⑧out["reference"] = {k: float(v) for k, v in reference_winrates(np.random.default_rng(0)).items()} 46 print("reference", out["reference"])
 47⑨json.dump(out, open(f"../results/bj2_blackjack_{HANDS}.json", "w"), indent=1)
下載包的 blackjack/scripts/bj2_blackjack.py 第 32–47 行

bj3_author_brain.py:BJ3,重新評分作者附的大腦

這支在做什麼。作者附了一個訓練完的蕈狀體狀態檔 data/brain_seed.json(PART 3 叫它大腦檔)。它是作者的網頁版用的:作者除了 Python 程式,還用 JavaScript 寫了一個在瀏覽器裡跑的版本(repo 的 site/,首頁〈出處〉提到的線上牌桌),本頁叫它網頁版。檔內標明它是從「Python 跑完 30,000 手、種子 0」的蕈狀體轉存成網頁版的格式(所以這支程式的說明寫 python session);檔內記的一致率 53.1%,是網頁版的 JavaScript 評分程式算的。這支程式把那份狀態載入作者的 Python 模型,用作者算一致率的那個函式(agreement,第 7 節)重算,得到 51.9%。這一節會出現好幾個一致率,先排好:

另一個比較:大腦檔標明是種子 0,本機種子 0 學完的表和它有 114 格選的動作不同(碰巧也是 114,和上面「與基本策略相同 114 格」是不同的比較;PART 3 第 5 節,這是課程 repo 的 scripts/part3_extras.py 逐格比的,不在下載包裡,這支 bj3 只算大腦檔自己的表)。原因的推論放在下面讀完程式之後(④ 之後那段)。要先弄清楚那個檔存了什麼。

  1 """BJ3:作者附的 30,000 手大腦(data/brain_seed.json,標記為 python 30k-hand session, seed 0)
  2 載入 Python 模型後重新評分,與作者自述(stand 約 227、double 0/39、一致率 53.1%)比較;與本機 BJ2 的比較在課程頁面上做(逐格比對在課程 repo 的 scripts/part3_extras.py)。
  3 gain 只存 18,183 條 KC→MBON 連結,順序依 site/mb.json 的 w_kc_mbon (r, c)。在 repo/ 下以 PYTHONPATH=. 執行。"""
  4 import json, base64
  5 import numpy as np
  6 from flybrain.mb.blackjack import FlyPlayer, chart_cells, basic_strategy, HIT, STAND, DOUBLE
  7 
  8①b = json.load(open("data/brain_seed.json"))  9②w = json.load(open("site/mb.json"))["w_kc_mbon"] 10③g = np.frombuffer(base64.b64decode(b["gain"]), np.uint8) / 255.0 11④fly = FlyPlayer(seed=0) 12⑤assert fly.mb.gain.shape == tuple(w["shape"]) and len(g) == b["n"] == len(w["r"])
下載包的 blackjack/scripts/bj3_author_brain.py 第 1–12 行
 13 # 先確認 site/mb.json 的連結位置與本機切出的電路相同
 14①raw = fly.mb.W_kc_mbon_raw 15②same_edges = bool(np.all(raw[w["r"], w["c"]] > 0) and (raw > 0).sum() == len(w["r"])) 16③gain = np.ones_like(fly.mb.gain); gain[w["r"], w["c"]] = g 17④fly.mb.gain = gain 18⑤out = dict(stored_agreement=b["agreement"], stored_units_per_hand=b["units"] / b["hands"], same_edges=same_edges, 19⑥           python_agreement=fly.agreement())
下載包的 blackjack/scripts/bj3_author_brain.py 第 13–19 行

第 20 到 28 行和 bj2_blackjack.py 的 spot_counts 同一件事(260 格各選什麼、各類選對幾格),印出來並存成 results/bj3_author_brain.json,不再重複講。PART 3 第 5 節那張表裡「要牌 97、停牌 149、加倍 14」出自這裡。程式第 2 行說明把「stand 約 227、double 0/39、一致率 53.1%」並列為作者自述,但來源不同:53.1% 是大腦檔裡記的,「stand 約 227、double 0/39」是作者在 blackjack.py 檔尾註解裡對學完模型的描述(那段註解寫的一致率是 48.1%),要分兩組比:停牌格數是作者寫約 227 格、大腦檔重算 149 格;加倍選對是作者寫 0/39、大腦檔重算 1/39。停牌差 78 格的原因,本課沒有查到:作者沒說那段描述來自哪一次跑,也沒有附那一次的存檔。PART 3 第 5 節整理了作者三份資料互相對不上的情形。表裡的「加倍 14」是 260 格裡它選加倍的總格數,和這兩組比較無關。

bj_extra.py:X1 到 X4

這支在做什麼。PART 4 的四項檢查,都在 21 點上做。它比前兩支長,因為 X2、X3 要「換一個不同的電路、或打亂某一層接線,再讓作者的 21 點程式打」,而作者的 FlyPlayer 建蕈狀體時用的是寫死的檔案與設定。不改作者程式又要換,用的辦法在第 32 到 38 行。

 17①from flybrain.mb import blackjack as bj 18②from flybrain.mb.model import MushroomBody 19③from flybrain.mb.extract import extract 20 
 21④HANDS = int(sys.argv[1]) if len(sys.argv) > 1 else 30000 22⑤OUT = Path("../results"); (OUT / "circuits").mkdir(parents=True, exist_ok=True) 23 res = {"hands": HANDS}
下載包的 blackjack/scripts/bj_extra.py 第 17–23 行
 26①def stats(v): 27②    v = np.asarray(v, float); se = v.std(ddof=1) / np.sqrt(len(v)) if len(v) > 1 else 0.0 28     return dict(n=len(v), mean=float(v.mean()), sd=float(v.std(ddof=1)) if len(v) > 1 else 0.0, 29                 ci95=[float(v.mean() - 1.96 * se), float(v.mean() + 1.96 * se)])
 30 
 31 
 32③def use_circuit(path=None, post=None, **mb_kw): 33     """讓 FlyPlayer 建蕈狀體時用指定的 npz 與設定,並可在建好後對 model 動手腳(post)。"""
 34④    def make(**kw): 35⑤        mb = MushroomBody(path=path or "data/mb_circuit.npz", **mb_kw, **kw) 36⑥        if post: post(mb) 37         return mb
 38⑦    bj.MushroomBody = make
下載包的 blackjack/scripts/bj_extra.py 第 26–38 行
 41①def play(seed, tag, **kw): 42     """一個種子打 HANDS 手,回傳每 2,000 手一塊的平均與一致率。"""
 43     t0 = time.time()
 44②    fly = bj.FlyPlayer(seed=seed, **kw) 45③    _, blocks, agree = bj.session(fly, hands=HANDS, seed=seed) 46④    r = dict(seed=seed, first_block=blocks[0], last_block=blocks[-1], agree_first=agree[0], agree_last=agree[-1], blocks=blocks, agree=agree) 47⑤    print(f"{tag:40s} seed {seed:2d}  winrate {blocks[0]:+.3f} -> {blocks[-1]:+.3f}  agree {agree[0]:.3f} -> {agree[-1]:.3f}  ({time.time() - t0:.0f}s)", flush=True) 48     return r
 49 
 50 
 51⑥def summarise(runs): 52     return dict(runs=runs, last=stats([r["last_block"] for r in runs]), agree_last=stats([r["agree_last"] for r in runs]))
下載包的 blackjack/scripts/bj_extra.py 第 41–52 行
 56①use_circuit() 57②SEEDS20 = list(range(20)) 58 x1 = {}
 59③for name, kw in [("connectome + dopamine", {}), ("dopamine cut + exploration decay", dict(dopamine=False)), 60                  ("untrained greedy", dict(learn=False, explore=0.0, explore_floor=0.0))]: 61④    x1[name] = summarise([play(s, f"X1 {name}", **kw) for s in SEEDS20]) 62⑤    x1[name]["first3"] = stats([r["last_block"] for r in x1[name]["runs"][:3]]) 63 res["X1_seeds20"] = x1 64 print("X1", {k: round(v["last"]["mean"], 4) for k, v in x1.items()}, flush=True)
下載包的 blackjack/scripts/bj_extra.py 第 56–64 行
 67 x2 = {}
 68 runs = []
 69①for s in range(5): 70②    use_circuit(shuffle_kc_mbon=True, seed=s)        # 作者 model.py 的 degree-preserving 打亂,每個種子一種 71     runs.append(play(s, "X2 KC->MBON shuffled")) 72③x2["kc_mbon_shuffled"] = summarise(runs) 73 perms = []
 74④for k in range(5): 75⑤    def perm_dan(mb, k=k): 76⑥        rng = np.random.default_rng(1000 + k) 77⑦        mb.W_dan_mbon = mb.W_dan_mbon[:, rng.permutation(mb.n_mbon)] 78⑧    use_circuit(post=perm_dan) 79⑨    runs = [play(s, f"X2 DAN->MBON perm {k}") for s in range(3)] 80     perms.append(dict(perm=k, **summarise(runs)))
 81 x2["dan_mbon_shuffled"] = dict(per_permutation=perms, mean_of_means=float(np.mean([p["last"]["mean"] for p in perms])), 82                                agree_mean_of_means=float(np.mean([p["agree_last"]["mean"] for p in perms])))
 83 res["X2_layers"] = x2
 84 print("X2", round(x2["kc_mbon_shuffled"]["last"]["mean"], 4), round(x2["dan_mbon_shuffled"]["mean_of_means"], 4), flush=True)
下載包的 blackjack/scripts/bj_extra.py 第 67–84 行

這段在做什麼。X2:打亂哪一層接線,21 點才學不會。兩層各打亂一次,PART 4 第 3 節。

 87①blocks, info = extract(kenyon=None)          # 全部在路徑上的 KC 88②n_live = blocks["pn_kc"].shape[1]
下載包的 blackjack/scripts/bj_extra.py 第 87–88 行

第 91 到 99 行的 save_npz 是作者 extract.py 第 99 到 110 行 save 的翻版(同樣四個陣列、同樣的壓縮),只是存到我們指定的路徑,不再重講。

102 x3 = {}
103①variants = {"all_live_kc": np.arange(n_live)}104 for k in range(3):105②    variants[f"random1200_{k}"] = np.sort(np.random.default_rng(500 + k).choice(n_live, 1200, replace=False))106 for name, idx in variants.items():107③    bl = dict(blocks); bl["pn_kc"] = blocks["pn_kc"][:, idx]; bl["kc_mbon"] = blocks["kc_mbon"][idx, :]108④    p = OUT / "circuits" / f"mb_{name}.npz"; save_npz(p, bl, info)109⑤    use_circuit(path=str(p))110⑥    x3[name] = dict(n_kc=int(len(idx)), **summarise([play(s, f"X3 {name}") for s in range(3)]))111 res["X3_kc_subsets"] = dict(n_live_kc=int(n_live), variants=x3)
112 print("X3", {k: round(v["last"]["mean"], 4) for k, v in x3.items()}, flush=True)
下載包的 blackjack/scripts/bj_extra.py 第 102–112 行
115①cells = json.loads(Path("data/mb_cells.json").read_text())116②types, nts, val = cells["types"]["mbon"], cells["nt"]["mbon"], cells["mbon_valence"]117③lit = {"glutamate": -1, "acetylcholine": 1, "gaba": 1}118 rows, tab = [], Counter()
119 for t, nt, v in zip(types, nts, val):120④    exp = lit.get(nt.lower())121     tab[(nt, v)] += 1122⑤    rows.append(dict(type=t, nt=nt, author=v, nt_rule=exp, agree=(exp == v) if exp is not None and v != 0 else None))123 judged = [r for r in rows if r["agree"] is not None]124 res["X4_mbon_valence"] = dict(125     rule="Aso et al. 2014 eLife:麩胺酸 MBON 活化促迴避(−1),乙醯膽鹼/GABA 促趨近(+1);簡化規則,有已知例外",
126     crosstab={f"{nt}|{v:+d}": n for (nt, v), n in sorted(tab.items())},
127⑥    judged=len(judged), agree=sum(r["agree"] for r in judged),128     disagree=[r for r in judged if not r["agree"]], cells=rows)129 print("X4", res["X4_mbon_valence"]["crosstab"], res["X4_mbon_valence"]["agree"], "/", len(judged), flush=True)
130 
下載包的 blackjack/scripts/bj_extra.py 第 115–130 行

這段在做什麼。X4:MBON 的趨近/迴避標記對文獻規則。這一項不用打牌,看的是電路本身。

最後兩行把四項結果一起寫成 results/bj_extra.json,本課收在 out/blackjack/bj_extra.json,PART 4 每一節末尾標的「X1_seeds20」「X2_layers」等就是這個檔裡的四個段落。

5第二層:check.py,驗收

這支在做什麼。run_all.sh 跑完的最後一步。它讀 expected.json(本課實跑的結果,每一項寫著「去哪個檔、取哪個值、用哪種標準比」),逐項去你的 results/ 與 logs/ 取值,比對後印 ✓ 或 ✗,共 17 項。PART 3 第 1 節講的三種判定標準,在這裡變成五種程式判法,本課用到其中兩種。對應關係:「逐位相同」對應 exact(比一個數)、same(比兩個檔)、contains(終端輸出裡出現預期的那幾行)、md5_twice(兩次的 md5 相同且等於預期)四種;「在誤差範圍內」對應 rel;「形狀相同」沒有程式判法,要人看。本課的 17 項是 exact 16 項加 md5_twice 1 項:驗收比的是你跑出來的和本課實跑的是否逐位相同,不是和作者比,和作者比的那一步在 PART 3。

  1 """驗收:把 run_all.sh 跑出來的數字跟 expected.json(本課實跑的結果)逐項比對。
  2 用法:python check.py blackjack   (在 pack 根目錄或子資料夾都可以)
  3 判定有五種:exact(逐位相同)、rel(相對誤差在容許範圍內)、
  4 same(兩個檔案內容相同)、contains(終端輸出裡出現預期的那幾行)、md5_twice(同一支程式跑兩次的 md5 相同且等於預期)。"""
  5①import json  6 import os  7 import sys  8 
  9②ROOT = os.path.dirname(os.path.abspath(__file__)) 10③SUB = {"blackjack": "blackjack"}
下載包的 check.py 第 1–10 行
 13①def get(path, keys, pluck=None, mean=False): 14②    with open(path) as f: 15         d = json.load(f) if path.endswith(".json") else f.read() 16③    for k in keys: 17         d = d[k] 18④    if pluck:                      # 一串 dict 裡取同一個欄位,例如每一局的 kills 19         d = [x[pluck] for x in d] 20⑤    if mean: 21         d = round(sum(d) / len(d), 6) 22     return d
下載包的 check.py 第 13–22 行
 25 def main(which):
 26①    exp = json.load(open(os.path.join(ROOT, "expected.json")))[which] 27②    base = os.path.join(ROOT, SUB[which]) 28     ok = bad = known = 0
 29③    for c in exp: 30         try:
 31④            got = get(os.path.join(base, c["file"]), c.get("keys", []), c.get("pluck"), c.get("mean", False))
下載包的 check.py 第 25–31 行
 32①            if c["kind"] == "exact": 33                 good = got == c["value"]
 34②            elif c["kind"] == "rel": 35                 v = c["value"]
 36                 good = abs(got - v) <= c["tol"] * max(abs(v), 1e-9)
 37③            elif c["kind"] == "same": 38                 other = get(os.path.join(base, c["other"]), [])
 39                 good = got == other
 40④            elif c["kind"] == "contains": 41                 good = all(v in got for v in c["value"])
 42⑤            elif c["kind"] == "md5_twice":     # 同一支程式跑兩次,兩行 md5 相同且等於預期 43                 h = got.split()[0::2]
 44                 good = len(h) == 2 and h[0] == h[1] == c["value"]
 45             else:
 46                 good = False
 47⑥        except (OSError, KeyError, IndexError, ValueError) as e: 48             got, good = f"讀不到({type(e).__name__})", False
下載包的 check.py 第 32–48 行

這段在做什麼。五種判法。if … elif … else 讀成「如果是這種…否則如果是那種…都不是就…」。

 49①        if not good and c.get("known"):         # 本課實跑時就不符、頁面上已說明的項目 50             known += 1 51             print(f"△ {c['step']:6s} {c['what']} 本次 {got!r};已知:{c['known']}") 52             continue
 53         ok += good
 54         bad += not good
 55②        mark = "✓" if good else "✗" 56         print(f"{mark} {c['step']:6s} {c['what']}" + ("" if good else f" 本次 {got!r},預期 {c.get('value', c.get('other'))!r}")) 57     tail = f",{known} 項已知不符(△,本課實跑時也一樣)" if known else ""
 58③    print(f"\n{which}:{ok} 項通過,{bad} 項不符{tail}(共 {ok + bad + known} 項)") 59     return bad
下載包的 check.py 第 49–59 行

6第三層:model.py,蕈狀體的活動量與學習規則

這支在做什麼。PART 1 第 3 節後半(KC 只留最高 6%、MBON 加權總和、好惡值)與第 4 節(多巴胺只會削弱)的全部公式。作者在檔頭用兩個英文大寫標題(MEASURED/INVENTED)分了兩類。量出來的是哪些 PN 連哪些 KC、哪些 KC 連哪些 MBON、哪些 DAN 能改哪些 MBON;他說最後這一項最重要,因為它讓「懲罰訊號能改什麼」由解剖決定,不是由參數決定。發明的是用活動量代替放電、學習率與回復速度與下限、用「只留前幾名」代替 APL 的抑制(APL 是真實蕈狀體裡一顆負責壓抑其他 KC 的抑制神經元)、以及氣味的對應。

 45①KC_SPARSITY = 0.06      # fraction of Kenyon cells active per odour (real: ~5-10%) 46②LEARNING_RATE = 0.55 47③DECAY = 0.012           # passive recovery of depressed synapses, per presentation 48④GAIN_FLOOR = 0.0 49⑤LATERAL = 0.25          # weight of measured MBON->MBON interactions
fly-blackjack 的 flybrain/mb/model.py 第 45–49 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
 59①def _normalise(W): 60     """Scale each postsynaptic cell's inputs to sum to one, as in circuit.py."""
 61②    s = W.sum(axis=0, keepdims=True) 62     s[s == 0] = 1.0 63     return W / s 64 
 65 
 66 class MushroomBody: 67③    def __init__(self, path="data/mb_circuit.npz", sparsity=KC_SPARSITY, 68                  learning_rate=LEARNING_RATE, decay=DECAY, lateral=LATERAL, 69                  shuffle_kc_mbon=False, seed=0): 70④        z = np.load(path) 71⑤        self.W_pn_kc = _normalise(_dense(z, "pn_kc")) 72⑥        self.W_kc_mbon_raw = _dense(z, "kc_mbon") 73⑦        self.W_dan_mbon = _normalise(_dense(z, "dan_mbon")) 74⑧        self.W_mbon_mbon = _normalise(_dense(z, "mbon_mbon")) 75⑨        self.valence = z["mbon_valence"].astype(np.float64) 76         self.punish_mask = z["dan_is_punishment"].astype(bool)
fly-blackjack 的 flybrain/mb/model.py 第 59–76 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。讀 extract.py 存的電路檔,做成四個權重矩陣。

 78①        if shuffle_kc_mbon: 79             # degree-preserving rewire: same number of partners per KC and per
 80             # MBON, different partners. A lesion control, not a topology claim.
 81             rng = np.random.default_rng(seed) 82             W = self.W_kc_mbon_raw 83②            flat = W[W > 0] 84③            rng.shuffle(flat) 85             out = np.zeros_like(W) 86④            out[W > 0] = flat 87⑤            for _ in range(3): 88                 perm = rng.permutation(out.shape[0]) 89                 out = out[perm] 90⑥            self.W_kc_mbon_raw = out 91 
 92⑦        self.W_kc_mbon = _normalise(self.W_kc_mbon_raw) 93         self.n_kc, self.n_mbon = self.W_kc_mbon.shape 94         self.n_pn = self.W_pn_kc.shape[0]
 95         self.n_dan = self.W_dan_mbon.shape[0]
 96⑧        self.k = max(1, int(round(sparsity * self.n_kc))) 97         self.lr, self.decay, self.lateral = learning_rate, decay, lateral 98⑨        self.reset()
fly-blackjack 的 flybrain/mb/model.py 第 78–98 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
104①    def pn_drive(self, pn_activity: np.ndarray) -> np.ndarray:105         """Projection-neuron input reaching each Kenyon cell.
106 
107         Separated out because it is linear: if an odour blend is a weighted sum
108         of fixed odours, so is the drive, and callers can precompute one vector
109         per odour instead of redoing this matrix product every step.
110         """
111②        return self.W_pn_kc.T @ pn_activity112 
113     def kenyon(self, pn_activity: np.ndarray) -> np.ndarray:
114         return self.kenyon_from_drive(self.pn_drive(pn_activity))
115 
116③    def kenyon_from_drive(self, drive: np.ndarray) -> np.ndarray:117         """Sparse odour code. k-winners-take-all stands in for APL inhibition."""
118④        if drive.max() <= 0:119             return np.zeros(self.n_kc)120⑤        cut = np.partition(drive, -self.k)[-self.k]121⑥        kc = np.where(drive >= cut, drive, 0.0)122⑦        top = kc.max()123⑧        return kc / top if top > 0 else kc
fly-blackjack 的 flybrain/mb/model.py 第 104–123 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。PART 1 第 3 節「KC 活動」那一條:每顆 KC 先算收到的 PN 活動 × 權重的總和,只留最高的 72 顆,再除以最大值。

125①    def dopamine(self, punish: float, reward: float) -> np.ndarray:126         dan = np.zeros(self.n_dan)127②        dan[self.punish_mask] = punish128③        dan[~self.punish_mask] = reward129④        return self.W_dan_mbon.T @ dan          # only where anatomy allows
fly-blackjack 的 flybrain/mb/model.py 第 125–129 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
131①    def present(self, pn_activity, punish=0.0, reward=0.0, learn=True, drive=None):132②        kc = self.kenyon_from_drive(self.pn_drive(pn_activity) if drive is None else drive)133③        mbon = (self.W_kc_mbon * self.gain).T @ kc134④        mbon = mbon + self.lateral * (self.W_mbon_mbon.T @ mbon)135⑤        da = self.dopamine(punish, reward)136⑥        if learn and (punish or reward):137⑦            self.gain -= self.lr * np.outer(kc, da)138         if learn:139⑧            self.gain += self.decay * (1.0 - self.gain)140⑨            np.clip(self.gain, GAIN_FLOOR, 1.0, out=self.gain)141         return dict(kc=kc, mbon=mbon, dopamine=da,142⑩                    valence=float(mbon @ self.valence),143                     sparsity=float((kc > 0).mean()))
fly-blackjack 的 flybrain/mb/model.py 第 131–143 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。整個模型的核心:呈現一次輸入。PART 1 第 3 節的 MBON 式與好惡值式、第 4 節的兩條學習式,全在這十三行裡。下一節的 21 點每一次「聞」都是叫它。

145①    def valence_of(self, pn_activity) -> float:146         """Read out without learning -- the test trial."""
147         return self.present(pn_activity, learn=False)["valence"]148 
149     @property
150②    def depression(self) -> float:151         """How far the plastic synapses have moved from naive, 0..1."""
152         mask = self.W_kc_mbon_raw > 0153         return float(1.0 - self.gain[mask].mean())
fly-blackjack 的 flybrain/mb/model.py 第 145–153 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

白話:為什麼懲罰打的是 +1(趨近型)那一群:學習規則只會削弱,懲罰要讓好惡值往負走,就只能削弱加分的那一邊;所以「懲罰多巴胺送得最多」的 MBON 要定成 +1,學習方向才會對(extract.py 的標記規則就是 PPL1 占多數標 +1)。作者的註解只寫了「+1 趨近(懲罰區)、−1 迴避(獎賞區)」,並引文獻說懲罰多巴胺作用在推動趨近的區;這裡從學習規則倒推的理由是本課的推論,作者沒有這樣寫。

懲罰怎麼讓好惡值變負。一種氣味進來,682 個 PN 的活動乘上接線,1,200 顆 KC 裡只讓最亮的 72 顆亮(第 120、121 行)。這 72 顆沿著各自的連結推 97 顆 MBON,每條連結的力道是「接線量到的權重 × 目前的增益」(第 133 行)。MBON 帶 +1 或 −1,加總就是好惡值(第 142 行)。如果這時有懲罰多巴胺,每顆 MBON 照它的 PPL1 比例收到一份,它和正在亮的 72 顆 KC 之間的連結增益被扣一截(第 137 行);一次懲罰的多巴胺有 97% 進了 +1 的 MBON(PART 1 第 4 節;算法:每顆 MBON 收到的多巴胺突觸先縮放成加總 1,一次懲罰給每顆 MBON 的量就是它的 PPL1 比例,把 97 顆加總,+1 的 56 顆佔 97%。另 38 顆 −1 的 MBON 雖然也接到 PPL1,但 PPL1 只佔它們輸入的一小部分:−1 那 41 顆共收 586 個 PPL1 突觸、27,807 個 PAM 突觸),所以下次同一種氣味再來,加分的那一堆推得比較弱,好惡值就往負走。

獎賞怎麼讓它變正。同一條路、對象相反:獎賞群 PAM 的多巴胺大多(93%)進了標 −1(迴避型)的 MBON,削弱的是扣分的那一堆,好惡值就往正走。21 點贏了之後「這個牌面配這個動作」的好惡值會升高,靠的就是這條路(第 7 節 outcome);規則永遠只有削弱,升或降看削弱的是哪一型 MBON 的輸入。

標記的限制。PART 4 的 X4 拿標記去對文獻裡的傳導物質規則,97 顆裡 62 顆一致。這要分兩件事。(a) 在現有的模型裡,學習方向一定是對的:方向只看懲罰多巴胺是不是主要進了標 +1 的 MBON,而標記本來就照這件事定,這是定義上的事,不必實測;所以標記和真果蠅對不對得上,不影響現在報告的 21 點結果。(b) 若把標記改成照文獻規則定,約三分之一會翻號,結果會不會變、變多少,本課沒跑(PART 4 推測會學得更差)。這些標記不能拿來談生物學。

兩個細節

少數標 −1、但也收到一點 PPL1 的 MBON,懲罰時同樣會被削,只是量小;整體往負走是多數決的結果,不是每一顆都這樣。每次以 learn=True 呈現,增益都往 1 爬回一點(第 139 行)。

7第三層:blackjack.py,21 點

這支在做什麼。PART 1 第 5 節的 21 點實驗,一個檔裝了四樣東西:21 點的規則與基本策略表(第 22 到 129 行)、牌面怎麼編成「氣味」(Situation,第 133 到 170 行)、會打牌的蕈狀體(FlyPlayer,第 174 到 235 行)、連打幾萬手(第 239 到 261 行)。檔尾第 265 到 295 行是作者用註解寫的結果與心得,PART 3 第 7 節引的就是它。先認識三個 21 點的詞:莊家兩張牌有一張翻開給你看,叫明牌;手裡有 A 算成 11 點而沒爆的叫軟手,其餘叫硬手;加倍是賭注變兩倍、只再抽一張就停,只能在剛拿到前兩張時做;開局兩張就 21 點叫黑傑克,直接贏 1.5 注。作者在檔頭說明為什麼選 21 點而不是撲克:情境很少(自己的點數、軟不軟、莊家明牌),每一格會被重訪幾百次,結果在同一手內揭曉,每一格的正確動作穩定,這正是「一次一筆聯想」的學習者(每次只把一個情境和它的結果連起來,不推理、不規劃)能靠平均摸出來的形狀;而且有一張公開的基本策略表當標準答案。作者的 repo 有四個實驗:氣味制約(讓模型聞氣味同時給獎或罰,看它之後躲不躲)、Dino 小遊戲、覓食、21 點;本頁只追 21 點。

規則與基本策略

 22①HIT, STAND, DOUBLE = 0, 1, 2 23 ACTION_NAMES = ["hit", "stand", "double"]
 24②CARDS = [2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 10, 10, 11]      # 11 = ace 25 
 26 
 27③def total(cards): 28     """(best total, is_soft). Aces count 11 until that busts."""
 29     t = sum(cards) 30     aces = cards.count(11) 31④    while t > 21 and aces: 32         t -= 10 33         aces -= 1 34⑤    return t, (aces > 0)
fly-blackjack 的 flybrain/mb/blackjack.py 第 22–34 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
 54①    if player_total >= 17: 55         return STAND 56②    if 13 <= player_total <= 16: 57         return STAND if up <= 6 else HIT 58③    if player_total == 12: 59         return STAND if up in (4, 5, 6) else HIT 60④    if player_total == 11: 61         return DOUBLE if (can_double and up <= 10) else HIT 62     if player_total == 10: 63         return DOUBLE if (can_double and up <= 9) else HIT 64⑤    if player_total == 9: 65         return DOUBLE if (can_double and up in (3, 4, 5, 6)) else HIT 66⑥    return HIT
fly-blackjack 的 flybrain/mb/blackjack.py 第 54–66 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。基本策略表的硬手部分(軟手在第 41 到 53 行,同一種寫法)。這就是「標準答案」:一致率比的對象。

 69①def chart_cells(): 70     """Every (total, soft, upcard) spot a first decision can land on."""
 71     cells = []
 72②    for up in range(2, 12): 73③        for t in range(5, 22): 74             cells.append((t, False, up)) 75④        for t in range(13, 22): 76             cells.append((t, True, up)) 77     return cells
fly-blackjack 的 flybrain/mb/blackjack.py 第 69–77 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
 81①def play_hand(policy, rng): 82     """policy(total, soft, upcard, can_double, legal) -> action.
 83     Returns (net units, list of (state, action) decisions)."""
 84②    draw = lambda: CARDS[rng.integers(len(CARDS))] 85③    player = [draw(), draw()] 86     dealer = [draw(), draw()] 87     up = dealer[0] 88     decisions = []
 89 
 90     pt, ps = total(player) 91     dt, _ = total(dealer) 92④    if pt == 21 and dt == 21: 93         return 0.0, decisions 94⑤    if pt == 21: 95         return 1.5, decisions 96⑥    if dt == 21: 97         return -1.0, decisions
fly-blackjack 的 flybrain/mb/blackjack.py 第 81–97 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
 99     bet = 1.0100     first = True101     while True:102         pt, ps = total(player)103①        legal = [HIT, STAND] + ([DOUBLE] if first else [])104②        a = policy(pt, ps, up, first, legal)105③        decisions.append(((pt, ps, up, first), a))106④        if a == STAND:107             break108⑤        player.append(draw())109         pt, ps = total(player)
110⑥        if a == DOUBLE:111             bet = 2.0112             break113         first = False114⑦        if pt > 21:115             return -bet, decisions116     pt, _ = total(player)
117     if pt > 21:
118         return -bet, decisions
119     while True:120         dt, ds = total(dealer)121⑧        if dt >= 17:122             break123         dealer.append(draw())124     dt, _ = total(dealer)
125⑨    if dt > 21 or pt > dt:126         return bet, decisions127     if pt < dt:128         return -bet, decisions129⑩    return 0.0, decisions
fly-blackjack 的 flybrain/mb/blackjack.py 第 99–129 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

Situation:牌面怎麼變成氣味

133①class Situation:134     """A spot plus a candidate action, as projection-neuron input.
135 
136     Ordered features (total, upcard) get overlapping codes so neighbouring
137     totals smell alike -- what the fly learns about hard 15 carries a little
138     to hard 14 and 16, which is how the chart is actually shaped. The action
139     gets the widest code, because the choice is the thing being learned.
140     """
141②    WIDTH = {"total": 26, "upcard": 22, "action": 36, "soft": 12, "first": 8}
fly-blackjack 的 flybrain/mb/blackjack.py 第 133–141 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
143     def __init__(self, mb: MushroomBody, seed=20260914):144         self.mb = mb
145①        rng = np.random.default_rng(seed)146         n = mb.n_pn147         self.drive = {}148②        for feature, levels, ordered in [("total", 18, True), ("upcard", 10, True),149                                          ("action", 3, False), ("soft", 2, False),150                                          ("first", 2, False)]:151             width = self.WIDTH[feature]152③            pool = rng.permutation(n)153④            for level in range(levels):154                 pn = np.zeros(n)155                 if ordered:156⑤                    start = int(level * width * 0.55)157⑥                    cells = pool[start:start + width]158                 else:159⑦                    cells = rng.choice(n, width, replace=False)160⑧                amp = 1.3 if feature == "action" else 1.0161⑨                pn[cells] = amp * rng.uniform(0.7, 1.0, size=len(cells))162⑩                self.drive[(feature, level)] = mb.pn_drive(pn)
fly-blackjack 的 flybrain/mb/blackjack.py 第 143–162 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
164①    def encode(self, pt, soft, up, first, action):165②        d = (self.drive[("total", int(np.clip(pt - 4, 0, 17)))]166              + self.drive[("upcard", up - 2)]167              + self.drive[("action", action)]168              + self.drive[("soft", int(soft))]169              + self.drive[("first", int(first))])170③        return d
fly-blackjack 的 flybrain/mb/blackjack.py 第 164–170 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

FlyPlayer:怎麼選、怎麼學

174 class FlyPlayer:175①    def __init__(self, seed=0, lr=0.05, decay=0.00005, explore=0.35,176②                 explore_floor=0.03, explore_halflife=3000,177                  learn=True, dopamine=True, credit_decay=1.0):178③        self.mb = MushroomBody()179④        self.mb.lr = lr180         self.mb.decay = decay181⑤        if not dopamine:182             self.mb.W_dan_mbon = np.zeros_like(self.mb.W_dan_mbon)183⑥        self.sit = Situation(self.mb)184         self.rng = np.random.default_rng(seed)185         self.learn = learn
186         self.explore0, self.explore_floor, self.halflife = explore, explore_floor, explore_halflife187         self.credit_decay = credit_decay
188⑦        self.hands = 0
fly-blackjack 的 flybrain/mb/blackjack.py 第 174–188 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)
190     def exploration(self):191①        return self.explore_floor + (self.explore0 - self.explore_floor) * 0.5 ** (self.hands / self.halflife)192 
193     def value(self, pt, soft, up, first, action):194②        return self.mb.present(None, learn=False,195                                drive=self.sit.encode(pt, soft, up, first, action))["valence"]196 
197     def greedy(self, pt, soft, up, first, legal):198③        vals = {a: self.value(pt, soft, up, first, a) for a in legal}199④        return max(vals, key=vals.get)200 
201     def policy(self, pt, soft, up, first, legal):202⑤        if self.rng.random() < self.exploration():203             return int(self.rng.choice(legal))204⑥        return self.greedy(pt, soft, up, first, legal)
fly-blackjack 的 flybrain/mb/blackjack.py 第 190–204 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。零件④(讀出規則)在 21 點裡的樣子:作者其他實驗在 MBON 後面另外接一層算動作的小網路(讀出網路);21 點沒有,直接拿好惡值比大小。

206     def outcome(self, net, decisions):207①        self.hands += 1208②        if not self.learn or not decisions:209             return210③        strength = float(np.clip(abs(net) / 2.0, 0.15, 1.0))211④        reward = strength if net > 0 else 0.0212         punish = strength if net < 0 else 0.0213⑤        if net == 0:214             return215         # Equal credit by default. Weighting the LAST decision most (an earlier
216         # version used 0.7**i) is a trap in blackjack: the last decision of a
217         # busted hand is always a hit and of a won hand is nearly always a stand,
218         # so "hit = lose, stand = win" became a global correlation that drowned
219         # every spot-specific lesson and the fly converged on always standing.
220⑥        for i, ((pt, soft, up, first), a) in enumerate(reversed(decisions)):221⑦            w = self.credit_decay ** i222⑧            self.mb.present(None, punish=punish * w, reward=reward * w, learn=True,223                             drive=self.sit.encode(pt, soft, up, first, a))
fly-blackjack 的 flybrain/mb/blackjack.py 第 206–223 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

這段在做什麼。學習規則在 21 點裡發生的地方:一手結束才回饋。

226①    def agreement(self):227         """Fraction of chart spots where the greedy choice matches basic strategy."""
228         hits = 0
229         cells = chart_cells()230         for (t, soft, up) in cells:231             legal = [HIT, STAND, DOUBLE]
232②            want = basic_strategy(t, soft, up, True)233③            got = self.greedy(t, soft, up, True, legal)234             hits += (want == got)235④        return hits / len(cells)236 
237 
238 # ----------------------------------------------------------------- session
239⑤def session(fly, hands=20000, seed=0, block=2000):240     rng = np.random.default_rng(seed)241     nets, blocks, agree = [], [], []242     for i in range(hands):243⑥        net, decisions = play_hand(fly.policy, rng)244⑦        fly.outcome(net, decisions)245         nets.append(net)246⑧        if (i + 1) % block == 0:247⑨            blocks.append(float(np.mean(nets[-block:])))248⑩            agree.append(fly.agreement())249     return np.array(nets), blocks, agree
fly-blackjack 的 flybrain/mb/blackjack.py 第 226–249 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)

第 252 到 261 行 reference_winrates 用同一個 play_hand 讓三種固定策略各打 20,000 手:基本策略、亂選、永遠停牌,就是 PART 3 第 4 節圖裡的三條參考線。第 265 到 295 行是作者的結果註解:他記的勝率與一致率、「它學到的是『別爆』」、以及上面提過的兩個坑。本課收在 out/upstream/blackjack_py_RESULT_comment.txt。

8停在哪裡:第三方套件與沒追的檔

第三層再往下就是別人寫的程式庫,本頁不展開。另外 repo 裡有一些檔案不在 21 點這條鏈上,列在這裡讓你知道它們存在。

套件或檔案誰用它做什麼進去的是什麼、出來的是什麼
numpy除了 check.py 以外的每一支 Python 程式一串或一張數字的運算:相乘加總(@)、排序、隨機抽樣、夾範圍進出都是數字陣列
scipy.sparsefetch.py、extract.py、bj_extra.py、model.py 的 _dense稀疏矩陣:只存非 0 格子的表進:.npz 檔;出:可以切塊、加總的矩陣
pandasfetch.py讀神經元屬性表(csv)、依欄篩選進:csv;出:表格
base64、jsonbj3、每一支Python 內建:位元組與可印字元互轉、讀寫 JSON—
odour.py21 點沒有用到把一個氣味名字變成 682 顆 PN 的活動量,給作者的制約與覓食實驗用;21 點的 Situation 自己把牌面變成 PN 活動,不經過它—
其他三個實驗的檔run_all.sh 沒有叫到train.py、circuit.py、readout.py、envs.py(Dino);experiment.py、tmaze.py(氣味制約);embodied.py、body/(覓食與會走路的身體)。各做什麼,PART 1 第 7 節簡介—
poker.py、cards.py、fasteval.py沒有人叫作者先試過撲克、失敗,檔尾記了為什麼;21 點的程式沒有引用它們—
web/、site/、export_web.py作者的網頁版與線上牌桌本課沒有重現;bj3 只讀了 site/mb.json 的連結位置清單,與作者附的 data/brain_seed.json—

表裡的 682 顆 PN 出自 out/blackjack/logs/bj1_extract_run1.log(PART 1 第 2 節的細胞數)。

9總表:每個檔案誰叫它;四個零件各在哪一行

檔案層誰叫它讀什麼寫什麼(本課 out/ 裡的對應)
setup_envs.sh一你—一個 conda 環境 flyplay_bj
run_all.sh一你—repo/、logs/ 每一步一個 log(out/blackjack/logs/)、results/
fetch.py二run_all.sh 第 13 行;extract.py 匯入它的 loadGitHub 上的兩個資料檔data/malecns/ 兩個檔;八行核對印在 bj1_fetch.log
extract.py二run_all.sh 第 14 行(兩次);bj_extra.py 匯入它的 extract連結矩陣、屬性表data/mb_circuit.npz(md5 在 bj1_md5.txt)、mb_manifest.json(印在 bj1_extract_run1.log)、mb_cells.json
bj2_blackjack.py二run_all.sh 第 15 行blackjack.py 的 FlyPlayer、session 等results/bj2_blackjack_30000.json;每行一個條件一個種子印在 bj2_blackjack.log
bj3_author_brain.py二run_all.sh 第 16 行作者的 data/brain_seed.json、site/mb.jsonresults/bj3_author_brain.json
bj_extra.py二run_all.sh 第 17 行blackjack.py、model.py、extract.py;mb_cells.jsonresults/bj_extra.json、results/circuits/ 四個電路檔
check.py二run_all.sh 第 18 行expected.json、上面所有輸出終端機上的 ✓/✗ 清單(out/blackjack/runall_test.out)
model.py三blackjack.py、bj_extra.py 匯入mb_circuit.npz(或 X3 的電路檔)不寫檔;回傳每一次呈現的 KC、MBON 活動、好惡值
blackjack.py三bj2、bj3、bj_extra 匯入model.py不寫檔;回傳每 2,000 手的平均與一致率

PART 1 第 6 節的總表,每一格換成檔案與行號:

零件在哪個檔、哪幾行
① 連結體extract.py 第 48 到 73 行切四群四層(第 3 節);model.py 第 70 到 76 行讀進來、第 59 到 63 行正規化
② 神經元方程式model.py 第 116 到 123 行(KC 只留 72 顆)、第 133 到 134 行(MBON 加權和 + 0.25 側向)、第 142 行(好惡值)
③ 輸入編碼blackjack.py 第 143 到 170 行(五個特徵的 PN 組相加)
④ 讀出規則MBON 標記:extract.py 第 75 到 79 行。選動作:blackjack.py 第 197 到 204 行(選好惡值最高,加探索)
學習model.py 第 136 到 140 行,兩條式子;參數在 blackjack.py 第 175 行;觸發點是 blackjack.py 第 222、223 行(一手結束才回饋)

好惡值與 ±1 標記分在兩格,是照 PART 1 總表的分法:好惡值那一行(model.py 第 142 行)是「MBON 活動 × 標記再加總」這條算式,屬於神經元方程式;每顆 MBON 的標記是 +1 還是 −1、以及拿好惡值怎麼選動作,是讀出規則。兩格合起來,才是「從 MBON 的活動得到要牌或停牌」的完整過程。

行數與常數出自 out/code_meta.json(由 scripts/make_code.py 從原檔抓);頁面上每一個程式區塊由同一支程式產生,--check 逐塊對回原檔。

← PART 5 逐手看蕈狀體怎麼打 回課程首頁 →
BSC 腦空間體研究中心 · 專題課程 蕈狀體學 21 點 · 教材由 Claude Code 產生 · 回課程首頁