PART 6
從 run_all.sh 那一支腳本開始,順著「誰叫了誰」讀三層:你親手執行的兩支腳本、它們叫到的六支 Python 程式、以及模型本身的兩個檔。每一段在做什麼、為什麼要有這一段;不教 Python 語法。讀完,PART 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 節)。
下面每一段都會用到這些詞,先在這裡說一次,之後不再解釋。
setup_envs.sh、check.py、expected.json、blackjack/,PART 2 第 3 節)。跑完之後它的 blackjack/ 底下會多出三個資料夾:repo/(作者的程式)、logs/(每一步印在終端機上的文字,一步一個檔)、results/(算出來的數字,JSON 格式:一種用大括號和冒號寫資料的文字檔)。out/:本課自己實跑時收下來的那一份 logs 與 results,放在本課網站的程式倉庫(GitHub 上的 marginli/bsc-flyblackjack)的 out/ 資料夾,給想核對的人用;expected.json 裡的標準答案就是從它抄的。不去拿也不影響讀這一頁。004b2e3 是本課固定的那一個(首頁〈出處〉)。MIT 授權:允許任何人複製、修改、散布,所以本頁可以直接引作者的程式。flyplay_bj(PART 2 第 4 節)。.. 是「上一層資料夾」。作者的程式在 repo/ 裡執行,所以我們的程式寫 ../results/,指的是 blackjack/results/。data/brain_seed.json,載入就等於拿到他訓練完的模型,第 4 節詳述);X1 到 X4:PART 4 本課自己加做的四項檢查。代號都是本課編的。W[i, j] 是第 i 列第 j 欄那一格。「一層神經元的活動乘上權重加總」在程式裡就是矩陣乘法,寫成 @。python -m flybrain.mb.fetch 讀成「執行 flybrain 資料夾底下 mb 資料夾裡的 fetch 這個模組」。class FlyPlayer: 定義會打牌的蕈狀體這種東西,FlyPlayer(seed=0) 做出一個;self 在方法裡指「這一個物件自己」。__init__ 是做出物件時第一個執行的方法。每一段程式都照同一個格式:先用一段話說這段在做什麼、為什麼要有這一段,然後放程式,程式下面逐行解釋。程式區塊左邊的數字是原檔的行號,和你下載下來的檔案完全一致;底色標出的行是接下來要講的行;行號旁的 ①②③ 是解釋裡用的標記。下面拿 run_all.sh 的兩行當例子:
6①PY="$(conda info --base)/envs/flyplay_bj/bin/python" 7②export PYTHONNOUSERSITE=1 PYTHONPATH=.
blackjack/run_all.sh 第 6–7 行flyplay_bj 這個環境的 Python 程式在哪裡)存進一個叫 PY 的名字裡,之後要用它時只要寫 $PY。這種「給一個東西取名字、之後用名字代替它」叫變數,程式裡到處都是。$(conda info --base) 是「問 conda 它裝在哪裡,把答案填進來」,不寫死路徑,換一台電腦也能跑。export 就是「之後叫出來的程式都看得到」)。PYTHONNOUSERSITE=1 叫 Python 不要去家目錄的 ~/.local 找套件,就是 PART 2 第 6 節那個「悄悄改變結果的陷阱」的擋法;PYTHONPATH=. 讓 Python 在目前資料夾找得到 flybrain 這個套件,因為作者的程式要在 repo/ 裡才匯入得到自己。本課自己寫的六個檔案在下載包裡;作者的檔案是 MIT 授權,run_all.sh 第一次跑會把整個 repo 放在 blackjack/repo/。兩邊都只放講到的段落,沒講到的行跳過(行號照原檔,缺的行可以打開檔案對照)。
建一個 conda 環境
一鍵重跑:取得程式與資料、BJ1 到 BJ3、X1 到 X4、驗收
BJ1:下載 MaleCNS 的連結矩陣、核對八個計數
BJ1:切出蕈狀體四群、算 MBON 的趨近/迴避標記
BJ2:四個條件 × 3 個種子 × 30,000 手
BJ3:把作者附的大腦檔載入 Python 模型重新評分
X1 到 X4,都在 21 點上做
驗收:你的結果對本課實跑的結果
蕈狀體:KC 的稀疏代碼、MBON、好惡值、學習規則
21 點:規則、牌面怎麼編成氣味、怎麼選動作、怎麼學
行數由 scripts/make_code.py 數出,記在 out/code_meta.json。本頁每一個程式區塊都由同一支程式從原檔照抄,make_code.py --check 會逐塊確認和原檔一致。make_code.py 是做這個網頁用的工具,放在課程網站的程式倉庫,不在下載包裡,run_all.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 行set -e:之後任何一行失敗,整支腳本立刻停。沒有這一行,建環境失敗了腳本還會繼續往下裝套件,錯誤會被埋掉。CONDA_BASE(第 1 節的例子解釋過 $(…))。# 後面灰色的字是註解:寫給人看的說明,電腦跳過不執行。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 行mk 的函式:把「建一個環境」這件事打包,之後叫一次就好。$1、$2 是叫它時給的第一、第二個值(環境名、Python 版本)。三個用 || 接起來的指令讀成「或者」:先看環境在不在(conda env list | grep),在就跳過建環境;不在就 conda create;連 create 都失敗,就加 --solver classic 再試一次。第 9 行的 pip install 前面是換行,不在這串「或者」裡,所以不管環境原本在不在都會跑,把套件裝成釘的那一版。最後那個備案是可攜測試時撞到的(可攜測試:把下載包解到一個空資料夾、從建環境開始從頭跑一次,確認不依賴本機原本就有的檔案與套件,PART 2 第 1 節;這是在同一台電腦上做的,不是真的換一台。換電腦也該得到相同數字,根據是作者固定了所有亂數種子、本課固定了套件版本,但本課沒有在第二台電腦上實測):conda 預設的求解器(決定裝哪些版本的那個零件)在某些安裝裡會壞掉。${@:3} 是「第三個以後的所有值」,也就是下一行列的套件清單。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 行mk 一次:環境名 flyplay_bj、Python 3.11、三個套件各釘在一個版本(==)。numpy 是數字陣列的運算,scipy 這裡只用它的稀疏矩陣(大部分是 0 的表格只存非 0 的格子,連結矩陣就是這種),pandas 讀表格檔。PART 2 第 4 節那張表就是這一行。這支在做什麼。它就是 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 行set -e:任何一步失敗就停,不會帶著錯的中間結果往下跑;後面的 -o pipefail 是給第 14 行用的。第 14 行是一條管線(for … done | tee …:前面的輸出經 | 接給 tee,tee 一邊印在螢幕上、一邊存檔),只有 set -e 時,一條管線成不成功只看最後一個指令 tee,迴圈裡切蕈狀體失敗了也不會停;加了 pipefail,管線裡任何一段失敗都算失敗。本課原本漏了這個,交稿前請沒看過頁面的人逐段讀、找問題時被抓到才補上(不影響任何結果)。blackjack/),存進 HERE。這樣不管你在哪個資料夾打 bash …/run_all.sh,它都知道 scripts/、logs/、results/ 在哪。第 6、7 行是第 1 節的例子。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 取。
[ -d repo ] || 讀成「如果 repo 這個資料夾還不存在,就」git clone:把 fly-blackjack 整個 repo 複製下來,放進 repo/。第二次跑就跳過。004b2e3… 是完整的四十個字,首頁〈出處〉寫的是前七個)。沒有這一行,作者之後改了程式,你跑到的就不是本課重現的那一版。logs/ 與 results/ 兩個資料夾,之後每一步的輸出往這裡放。repo/。作者的程式要在這裡執行(第 7 行的 PYTHONPATH=. 指的「目前資料夾」就是它:「.」不是在第 7 行設定的那一刻就定下的,而是之後每次 Python 啟動、要找套件時,才看當下在哪個資料夾),所以下面每一行寫到我們自己的檔案都是 ../ 開頭:往上一層回到 blackjack/。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/。
flybrain.mb.fetch 下載兩個資料檔(約 107 MB)並核對計數(第 3 節)。for i in 1 2; do … done 讓中間那段對 1、2 各跑一次。每次執行作者的 flybrain.mb.extract 切一次蕈狀體(輸出寫到 bj1_extract_run1.log、run2.log),再用 md5sum 算切出來的檔案 data/mb_circuit.npz(npz:numpy 把好幾個數字陣列打包成一個檔的格式,不是文字檔,直接打開看不懂)的指紋(md5:從整個檔案算出來的一串字,內容差一個位元就完全不同)。| tee 把兩行指紋同時印在螢幕上和存進 bj1_md5.txt。PART 3 第 3 節「跑兩次、md5 相同」驗的就是這個檔。bj2_blackjack.py 後面跟著四個數字:30000 是每個種子打幾手,0 1 2 是三個種子。PART 2 第 6 節教你把這一行單獨打出來、數字換成 2000 0 試跑(這支程式在本頁第 4 節):那樣只跑 BJ2 的種子 0 打 2,000 手,不經過 run_all.sh,所以 X1–X4 與驗收都不會跑,也就不會出現 ✗。bj3_author_brain.py,把作者附在 repo 裡的大腦檔載入 Python 模型重新評分(PART 3 第 5 節)。bj_extra.py 一支裡(第 4 節)。blackjack/,跑上一層的 check.py 驗收,blackjack 是告訴它驗哪一組。PART 2 第 7 節那份 ✓/✗ 的清單就是它印的(第 5 節)。fetch.py、extract.py,我們的 bj2_blackjack.py、bj3_author_brain.py、bj_extra.py、check.py。下面三節照這個順序讀。
這兩支是「有命令列入口」的作者程式(命令列:你在終端機打的那一行,程式名後面跟的字;本頁一律叫命令列):檔案最後一段寫著 if __name__ == "__main__":,意思是「這個檔被直接執行(而不是被別人匯入)時,做下面這些事」。run_all.sh 的 -m 就是從那一段進去。每一支的順序都一樣:先看入口那一段知道它收什麼設定,再往上看被叫到的函式。
這支在做什麼。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 }
flybrain/mb/fetch.py 第 14–31 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)main 分支(主分支:一個 repo 最新的那條版本線,會變)。PART 2 說「作者的下載程式沒有固定那個 repo 的版本」,看的就是這兩行的 main。repo/data/malecns/。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
flybrain/mb/fetch.py 第 134–145 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)out/blackjack/logs/bj1_fetch.log):這份 log 出自本機的實跑資料夾,那裡的兩個資料檔在更早的一次執行就下載好了,這次直接沿用。這裡有兩次執行,要分清楚。A 是本機實跑:資料早已下載,log 印 have;expected.json 的標準答案出自這一次,它的驗收輸出是 out/blackjack/runall_test.out(檔名有 test,但它是實跑 A 的輸出,不是可攜測試)。B 是可攜測試:從空資料夾開始,log 印 got(真的下載了),17 項全部通過(17 項是 check.py 的驗收項目,第 5 節),結果記在 out/porttest.json。分清楚的用意:A 沿用舊檔,沒有真的下載;B 真的從頭下載也全數通過,證明 A 沿用舊檔不影響結果。_fetch_one 下載。那個函式有 59 行(第 73 到 131 行),處理斷線續傳、憑證問題、改用 curl 的備案,本頁跳過:它只影響「下載會不會成功」,不影響任何數字。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 }
flybrain/mb/fetch.py 第 162–175 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。八個計數怎麼算出來。這裡第一次看到連結矩陣長什麼樣。
load()(第 148 到 159 行,本頁沒引)把兩個檔讀進來:M 是連結矩陣,一張 161,429 × 161,429 的表,第 i 列第 j 欄是「神經元 i 連到神經元 j 有幾個突觸」,絕大多數格子是 0,所以存成稀疏矩陣;meta 是神經元屬性表,一列一顆,有型(type:每顆神經元的細分名稱,例如 KCab-p、MBON01)、類(class:粗分類)等欄位。nnz);突觸數是所有格子加總。^KC 是「開頭是 KC」的寫法)。ALPN(觸角葉投射神經元):PN 的型名各帶自己小球區的名字(小球區:嗅覺訊號進腦第一站裡的分區,每一區收一種受體的訊號;例如 DA1_lPN 是 DA1 區的 PN),不以同一個字開頭,所以只能用粗分類挑。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)
flybrain/mb/fetch.py 第 177–189 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)ok &= good:第 176 行(就在這段上面一行)先把 ok 設成成立(True);之後只要有一項不符,ok 就變成不成立,而且不會再變回來。exit(1):程式結束時交給終端機一個數,叫結束碼,0 是成功、非 0 是失敗),run_all.sh 第 4 行的 set -e 看的就是這個數,非 0 就讓整支腳本在這裡停住。這就是 PART 2 說「日後整理版若更新,BJ1 會在這裡停住,而不是悄悄算出不同的蕈狀體」。這支在做什麼。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")
flybrain/mb/extract.py 第 42–51 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)extract 函式收兩個設定:要幾顆 KC(預設 1,200;給 None 就全部)、以及一個種子(這個版本沒用到它)。PART 4 的 X3(本頁第 4 節的 bj_extra.py)給 None 切全部 KC 就是走這裡。load() 讀連結矩陣與屬性表(上一節)。where:一個小工具,給一個「型的開頭」,回傳符合的神經元在矩陣裡的列號。KC_all:這是全部 4,064 顆,下面才會篩。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)])]
flybrain/mb/extract.py 第 53–65 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。PART 1 說「KC 只留同時接到 PN、又連到 MBON 的 3,811 顆,再依排名等距取 1,200 顆」,就是這十三行。
M[PN][:, KC_all]:矩陣裡只取「列是 PN、欄是 KC」那一塊;sum(axis=0) 沿著列加總,得到每顆 KC 從全部 PN 收到幾個突觸。& 是「而且」),共 3,811 顆。kind="stable" 是穩定排序:分數相同的保持原本順序。作者的註解寫得很直接:大多數 KC 在這個分數上同分,不穩定的排序在不同 numpy 版本會把同分的排成不同順序,於是「不同電腦悄悄拿到不同的一批細胞」。作者 repo 的 README 裡〈Reproducibility〉(可重現性)一節承諾切出來的檔案 md5 在不同電腦上相同,靠的就是這個字。linspace(0, 3810, 1200) 在排名 0 到 3810 之間等距取 1,200 個位置,所以取到的是「從最常連到最少連」全範圍都有,而不是只取前 1,200 名。這一行是 PART 1 第 6 節總表說「KC 只取 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
flybrain/mb/extract.py 第 67–79 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)kc_kc 那一塊,作者在檔頭說明寫了理由(真實的 KC 壓抑來自 APL 這顆抑制神經元,不是 KC 彼此的連結)。scripts/dan_counts.py 算出,在 out/blackjack/dan_counts.json 的 by_author_label)。這個 ±1 之後算好惡值時用:好惡值 = 每顆 MBON 的活動量 × 它的標記加總,趨近型加分、迴避型減分(第 6 節)。先講清楚性質:這個 ±1 是作者用接線定的規則,不是量出來的生理事實;為什麼這樣定、後果是什麼,第 6 節末的白話一次講完。這條對應在程式裡只有這一行。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)
flybrain/mb/extract.py 第 99–110 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)save:把四塊連結與兩串標記存成一個檔 data/mb_circuit.npz,就是 BJ1 算 md5 的那個檔。savez_compressed:numpy 的「把好幾個陣列壓縮存成一個檔」。壓縮方式固定,所以同樣的內容會得到同樣的位元,md5 才比得出來。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
flybrain/mb/extract.py 第 112–130 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)data/mb_manifest.json。作者執行時寫出的這個檔跟著 repo 一起 commit 進去,本課收在 out/upstream/blackjack_mb_manifest_committed.json;本機重切時又寫一次,印在 bj1_extract_run1.log,兩者完全相同。data/mb_cells.json:每顆神經元的型、位置、傳導物質、MBON 標記、DAN 群別。X4 讀它拿 MBON 的傳導物質(傳導物質:神經元放訊號時釋放的化學物質,資料集附的是預測值;第 4 節)。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))
flybrain/mb/extract.py 第 133–140 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)--kenyon,預設 1200,可以給 all。run_all.sh 沒給,所以是 1,200。bj1_extract_run1.log 的全部內容。這三支都在下載包的 blackjack/scripts/。共同原則寫在 PART 3 第 2 節:只匯入作者的函式,不修改它;結果寫到 ../results/,不碰作者的 data/。前兩支很短,因為工作只是「照作者在註解裡寫的設定,把他的函式叫一遍,然後把數字存下來」;第三支要換電路、打亂接線,長一點。
這支在做什麼。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 行FlyPlayer(會打牌的蕈狀體,一個類別)、session(讓它連打幾萬手)、reference_winrates(三種固定策略的參考勝率)、chart_cells(基本策略表的 260 格)、basic_strategy(每一格的正確動作)、以及三個動作的代號。基本策略是賭場數學算出來、公開的一張表:自己的手牌(26 種)對莊家亮出來的那張牌(10 種)共 260 種情況,每一格寫明該要牌、停牌還是加倍(加倍:賭注加倍、只再抽一張就停,只能在剛拿到前兩張牌時做);一致率是模型在這 260 格的選擇有多少比例和表相同。牌面怎麼分 26 種、三個動作的規則,在 第 7 節。dopamine=False),探索照常。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 格裡的選擇」表(要牌幾格、停牌幾格、加倍幾格)是這裡數的。
spot_counts:給一個打完的 FlyPlayer,數它在 260 格各選什麼。greedy(不探索、純照好惡值選)會選哪個動作,三種動作的計數各加一。True 是「當作前兩張」,所以加倍也在候選裡。chart_double_matched: 1/39 就是同一種算法。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 行s,加上這個條件的設定。**kw 是「把字典裡的設定全部展開當參數」。session 打 30,000 手,發牌的亂數也用同一個種子。種子只改兩件事:發牌與探索的亂數。電路、Situation 的編碼(第 7 節,固定種子 20260914)在所有種子下都相同,所以未訓練那組三個種子的成績差別只來自發牌。回來三樣:每一手的淨輸贏 nets、每 2,000 手一塊的平均 blocks(15 塊)、每一塊結束時與基本策略的一致率 agree。blocks。results/bj2_blackjack_30000.json,檔名帶手數。這支在做什麼。作者附了一個訓練完的蕈狀體狀態檔 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 行gain(增益:乘在每條 KC→MBON 連結上的一個倍率,1 是原始強度,學習只會把它往下壓、最低到 0;PART 1 第 4 節說學習改的就是這個數)、n(幾條)、agreement(檔內記的一致率)、units 與 hands(總輸贏與手數)。site/mb.json 裡 KC→MBON 那一層的「哪一列、哪一欄」清單。大腦檔的 gain 只存了 18,183 條有連結的格子、沒存位置,位置要靠這份清單。gain 解碼:它用 base64(把一串位元組寫成可印字元的編法)存了 18,183 個 0 到 255 的整數,除以 255 還原成 0 到 1 的增益。所以網頁版存的增益精度只有 1/255。檔內記錄的 53.1% 與載入 Python 重算的 51.9% 差 3 格,是不是這個精度造成的,本課沒有查。assert:不成立就立刻停):本機蕈狀體的增益矩陣形狀要和 mb.json 說的一樣,三個長度要相等。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 行same_edges,本課實跑是 true(out/blackjack/bj3_author_brain.json)。沒有這一步,重算的一致率就沒有意義。agreement 函式重算一致率,就是表裡的 51.9%。第 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 格裡它選加倍的總格數,和這兩組比較無關。
這支在做什麼。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 行bj。之後 bj.FlyPlayer、bj.session 就是第 7 節那兩樣東西。MushroomBody 類別(第 6 節)。extract 函式:X3 要用它切「全部 KC」的電路。$PY ../scripts/bj_extra.py 2000 試跑(單獨打要先做 run_all.sh 前幾行做的事:進到 blackjack/repo/、設好 PY 與 PYTHONPATH=.;PART 2 第 6 節列了完整指令),之後又跑 check.py,X1–X4 那幾項會出現 ✗,這是正常的。../results/,另開一個 circuits/ 子資料夾放 X3 切出來的幾個電路檔。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 行stats:給一串數(每個種子最後 2,000 手的平均),算四樣:幾個、平均、標準差(每個數離平均通常差多少)、95% 信賴區間(只跑了幾個種子,平均帶著誤差;這個範圍約 95% 會包含跑無限多個種子的平均)。PART 4 用它判定:完整模型和對照組的區間不重疊,就算兩者確實不同,不是幾副牌的運氣。ddof=1(樣本標準差,除以 n − 1),標準誤 = 標準差 ÷ √n;區間 = 平均 ± 1.96 × 標準誤。PART 4 第 2 節那條公式。種子只有 3 或 5 個時,嚴格的做法要把 1.96 換成 t 分布的係數(3 個是 4.30、5 個是 2.78),區間會更寬(樣本很少時,連「每個種子差多少」都估不準,平均的不確定性比 1.96 估的大,t 分布是照樣本數修正後的係數);這支程式一律用 1.96,是本課的簡化,PART 4 第 2 節列了改用 t 分布的區間,判定結果不變。use_circuit:這支程式的關鍵。作者的 FlyPlayer(第 7 節第 178 行)建蕈狀體時寫的是 MushroomBody(),去找的是 blackjack 模組裡那個叫 MushroomBody 的名字:blackjack.py 第 20 行寫了 from .model import MushroomBody,把 model.py 的類別匯入成 blackjack 模組裡的一個名字,我們換掉的就是這個名字。make 函式,收同樣的設定。path,沒給就用作者預設的 data/mb_circuit.npz),以及其他設定(mb_kw,X2 用它開「打亂 KC→MBON」)。post(一個「事後動手腳」的函式),就叫它一次。X2 打亂 DAN→MBON 從這裡進去。MushroomBody 名字換成我們的 make。之後作者的 FlyPlayer 寫 MushroomBody() 時,叫到的其實是 make。作者的檔案一個字都沒改,改的只是執行時那個名字指向誰。PART 4 第 1 節說「不改作者的模型」,做法就是這一行。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 行play:一個種子打 HANDS 手。四項檢查的每一次「跑」都是叫它。seed,加上這一項檢查要改的設定(**kw 是「把字典裡的設定全部展開當參數」,X1 的切斷多巴胺、未訓練就是從這裡給)。session 打 HANDS 手,發牌的亂數也用同一個種子。回來每 2,000 手一塊的平均 blocks 與一致率 agree。summarise:一串種子的結果,加上「最後 2,000 手平均」與「最後的一致率」各自的 stats。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 行dopamine=False)、未訓練(不學、不探索)。設定和 bj2_blackjack.py 的同名條件相同。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 節。
shuffle_kc_mbon=True,第 6 節第 78 到 90 行;註解裡的 degree-preserving=「保留每顆的夥伴數」是照抄作者的說法,實際做法和它有出入,見第 6 節那段的 ①),打亂用的種子就是這一輪打牌的種子 s,s 不同,打亂也不同,所以 5 個種子是 5 種不同的打亂。perm_dan(k=k 是把目前的 k 鎖進這個函式,Python 的迴圈變數不這樣寫會全部指到最後一個值)。permutation(97) 是 0 到 96 的隨機排列,[:, …] 是「列不動、欄照這個排列重排」。效果是每顆 DAN 原本連到的那組 MBON,整組被換成另一組,連結強度不變、MBON 的趨近/迴避標記也不動。重排的用意:讓懲罰多巴胺不再集中在 +1 那群,削弱的方向就和標記脫鉤(原理見第 6 節末的白話,結果在 PART 4 第 3 節)。mean_of_means,就是 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 行extract(kenyon=None),切一次全部 3,811 顆路徑上的 KC(第 3 節 extract.py 第 58 行那個條件不成立,就不取樣)。回來四塊連結與細胞資訊。第 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 行use_circuit 讓 FlyPlayer 改用這個檔。換了 KC 數,model.py 第 96 行「留 6%」(每種氣味只讓 6% 的 KC 亮,第 6 節)會跟著變:3,811 顆時留 229 顆。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 的趨近/迴避標記對文獻規則。這一項不用打牌,看的是電路本身。
data/mb_cells.json。Counter() 是一個「逐類計數」的字典,每遇到一個(傳導物質, 標記)組合就把那一類加 1,最後得到交叉表。最後兩行把四項結果一起寫成 results/bj_extra.json,本課收在 out/blackjack/bj_extra.json,PART 4 每一節末尾標的「X1_seeds20」「X2_layers」等就是這個檔裡的四個段落。
這支在做什麼。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 行import:把 Python 內建的三個套件接進來用。json 讀寫 JSON 檔,os 處理路徑,sys 讀命令列給的參數。第 1 到 4 行三個引號夾的是這支程式的說明文字,和註解一樣不執行。ROOT:這支程式自己所在的資料夾(下載包的最上層),和 run_all.sh 的 HERE 同一個想法。"blackjack" 這一組對到子資料夾 blackjack。本課原本和另一個重現專題(fruitfly-lab,在射擊遊戲 Doom 裡跑果蠅視覺迴路)合成一門課,這支程式那時同時驗兩個專案,字典是那時留下的形狀;拆成兩門課之後本課只有一組。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 行def get(…):定義一個函式,叫 get,工作是「打開一個檔,沿著一串鍵走進去,取出一個值」。括號裡是它收的四樣東西:檔案路徑、鍵的串列、可選的 pluck 與 mean。.json 結尾就當 JSON 解析,否則整個當文字讀進來(log 檔走這條)。for k in keys:對鍵的串列裡每一個鍵做一次 d = d[k],也就是一層一層往裡面走。例如 BJ2 那四項寫 ["conditions", "connectome + dopamine", "mean_last"],就是先進 conditions、再進那個條件、再取 mean_last。pluck:遇到「一串東西」時從每一個裡取同一個欄位。本課沒有一項用到,是拆課前留下的;第 18 行註解裡的「每一局的 kills」(擊殺數)也是 Doom 那門課的欄位。mean:把那串數字取平均。本課沒有一項用到。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 行which 是 run_all.sh 第 18 行給的 blackjack)。ROOT/blackjack。c)做一次下面的事;ok、bad、known 三個計數器從 0 開始。get 取值,存進 got。try 的意思是「試著做,失敗了跳到第 47 行」,檔案不存在也不會讓整支程式當掉,而是記成一項不符。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 讀成「如果是這種…否則如果是那種…都不是就…」。
exact:逐位相同,取到的值要和預期一模一樣。本課除了 BJ1 之外每一項都用它。17 項的分配:BJ1 的 md5 1 項、BJ2 四個條件的平均 4 項、BJ3 2 項(一致率、電路連結位置相同)、X1 三個條件 3 項、X2 兩層 2 項、X3 四種選法 4 項、X4 1 項;清單就是 expected.json。可以要求逐位相同,是因為 check.py 比的對象是本課的實跑結果,不是作者的數字;而 21 點的發牌與探索都固定了種子(PART 3 第 1 節)。rel:相對誤差。abs(got − v) 是差距的絕對值,不能超過預期值乘上容許比例 tol。本課沒有用到:沒有哪一步沒固定種子。same:兩個檔案內容相同。本課沒有用到。contains:檔案裡要出現預期的那幾段文字。本課沒有用到。md5_twice:同一支程式跑兩次,兩行 md5 要相同、而且等於預期。BJ1 用它:讀 bj1_md5.txt,split()[0::2] 是把檔案切成一個個字、每隔一個取一個,也就是兩行各自開頭的那串指紋;兩串要相同且等於 32dc4935…。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 行known 的項目,本課實跑時就不符、頁面上已經說明。這一包沒有一項標 known,所以 PART 2 第 7 節的最後一行只有「通過」與「不符」兩個數。continue 是跳到下一項。out/porttest.json)。第 59 行把不符的數目交回去,第 62、63 行(本頁沒引)用它決定程式的結束碼(程式結束時告訴終端機成功或失敗的一個數:0 是成功、1 是失敗):有不符就回 1。這支在做什麼。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
flybrain/mb/model.py 第 45–49 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)learn=True 呈現一種氣味(呈現=把一種氣味送進模型算一次,就是第 131 行的 present,本節後面逐行讀;learn=True 時順便改增益,learn=False 只讀分數、不改),被壓低的增益往 1 回復多少(21 點裡這只發生在一手有輸贏之後、逐一回饋這手每個決定的那幾次;選動作時的讀分用 learn=False,平手的手不回饋,都不算);21 點換成 0.00005。注意回復作用在整張 1,200 × 97 的增益表(第 139 行),不只剛呈現的那一種氣味:每一次 learn=True 的呈現,所有被壓低的連結都往 1 爬一點,所以別的牌面打多了,這一格的教訓也會被慢慢沖掉(第 7 節第一個坑)。作者特別註明這一項是「遺忘」,不是真實果蠅的消退(消退:學過的反應因為再沒有獎懲而被主動抹掉的過程;真實的消退是主動的多巴胺過程,這裡沒有模擬)。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)
flybrain/mb/model.py 第 59–76 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。讀 extract.py 存的電路檔,做成四個權重矩陣。
_normalise:作者註明「和 circuit.py(他另一個實驗 Dino,一個躲障礙的小遊戲,用的迴路檔,本課不碰)一樣,把每顆下游神經元的輸入縮放到加起來是 1」。_dense 在第 52 到 56 行,把 extract.py 存的四個陣列還原成一整張表)。raw,因為打亂與「哪些格子有連結」都要用原始的。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()
flybrain/mb/model.py 第 78–98 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)reset(第 100、101 行):增益矩陣全部設成 1:一張 1,200 × 97 的表(每顆 KC 對每顆 MBON 一格),其中 18,183 格有連結、其餘格子乘上 0 的權重沒有作用。這就是「沒學過任何東西」的狀態。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
flybrain/mb/model.py 第 104–123 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。PART 1 第 3 節「KC 活動」那一條:每顆 KC 先算收到的 PN 活動 × 權重的總和,只留最高的 72 顆,再除以最大值。
pn_drive:PN 的活動量進到每顆 KC 的總量。作者把它獨立出來,因為它是線性的:兩個輸入相加的驅動等於各自驅動的和,所以 21 點可以先算好每個特徵的驅動,打牌時直接相加(第 7 節會用到)。.T 是轉置:把表的列和欄對調。權重表是「列=上游、欄=下游」,對調後再乘,算出來的才是「每顆下游神經元收到多少」;後面的 dopamine、present 用到的 .T 也是同一個意思。kenyon_from_drive:從驅動算 KC 活動。作者註明「只留前 k 名代替 APL 的抑制」(APL 是真實蕈狀體裡負責壓抑其他 KC 的那顆抑制神經元)。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
flybrain/mb/model.py 第 125–129 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)dopamine:給懲罰強度與獎賞強度,算每顆 MBON 收到多少多巴胺。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()))
flybrain/mb/model.py 第 131–143 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。整個模型的核心:呈現一次輸入。PART 1 第 3 節的 MBON 式與好惡值式、第 4 節的兩條學習式,全在這十三行裡。下一節的 21 點每一次「聞」都是叫它。
present 收:PN 活動量(或直接給算好的驅動 drive)、懲罰強度、獎賞強度、要不要學。* 是逐格相乘:每條連結的權重乘上它目前的增益,被壓過的連結就變弱。outer 是外積:1,200 個 KC 活動和 97 個多巴胺值兩兩相乘,得一張 1,200 × 97 的表,剛好和增益矩陣同形狀。只有「這顆 KC 在亮、而且這顆 MBON 有收到多巴胺」的格子才會被扣。PART 1 第 4 節的第一條式子。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())
flybrain/mb/model.py 第 145–153 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)valence_of:呈現但不學,只拿好惡值。作者註解叫它「測試試驗」。21 點裡沒有用到它,FlyPlayer 直接叫 present 並設 learn=False。depression:有連結的格子的增益平均離 1 多遠,0 是全新、1 是全壓到底。21 點沒有用到。白話:為什麼懲罰打的是 +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 行)。
這支在做什麼。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)
flybrain/mb/blackjack.py 第 22–34 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)total:一手牌的最佳點數,以及是不是軟手。A 先算 11。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
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
flybrain/mb/blackjack.py 第 69–77 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)chart_cells:表上每一格。scripts/row21_visits.py 算出,在 out/blackjack/row21_visits.json)。PART 1 第 5 節扣掉這 20 格重算過:學完的一致率上升全部來自它們(20 個種子平均從 47.9% 降成 44.4%,未訓練扣掉後是 46.25%),也就是說,在其餘 240 格上一致率沒有因學習而提高;實際打牌仍會遇到 4 點,所以下面的編碼多留一格給它(18 種)。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
flybrain/mb/blackjack.py 第 81–97 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)play_hand:打一手。收一個「策略」函式(給點數、軟不軟、明牌、是不是前兩張、合法動作,回一個動作)與亂數產生器;回傳淨輸贏(以一注為單位)與這手做過的每一個決定。FlyPlayer 的 policy、基本策略、亂選、永遠停牌,都是塞進這個洞的不同函式。decisions 是空的:這一手沒有任何決定,所以也不會學。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
flybrain/mb/blackjack.py 第 99–129 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)decisions。一手結束後學習要回頭看的就是這份清單。total 回的是最佳點數)。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}
flybrain/mb/blackjack.py 第 133–141 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)Situation:「一個情境加一個候選動作,寫成 PN 的輸入」。作者的說明:有順序的特徵(點數、明牌)用重疊的代碼,讓相鄰的點數聞起來相近,模型對硬 15 學到的會帶一點到硬 14 與 16,基本策略表實際上就是這個形狀;動作拿最寬的代碼,因為要學的就是動作。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)
flybrain/mb/blackjack.py 第 143–162 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)pool。level × 寬度 × 0.55 顆開始、連取「寬度」顆。相鄰兩種值的起點只差 0.55 個寬度,所以約 45% 的 PN 共用。起點用 int() 捨去小數:點數一組 26 顆,26 × 0.55 = 14.3,所以起點實際每次差 14 或 15 顆,相鄰兩組共用 12 或 11 顆,就是 PART 1 說的「相鄰點數共用 11 或 12 顆」。pn_drive,第 6 節)。打牌時只要把五個驅動相加,不必每次做 682 × 1,200 的矩陣乘法。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
flybrain/mb/blackjack.py 第 164–170 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)encode:給點數、軟不軟、明牌、是不是前兩張、候選動作,回一個驅動。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
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)
flybrain/mb/blackjack.py 第 190–204 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。零件④(讀出規則)在 21 點裡的樣子:作者其他實驗在 MBON 後面另外接一層算動作的小網路(讀出網路);21 點沒有,直接拿好惡值比大小。
value:某個情境配某個動作的好惡值。叫蕈狀體 present,learn=False,只讀分數不學。greedy:對每個合法動作各算一次好惡值。policy:以探索比例的機率隨機從合法動作裡選一個。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))
flybrain/mb/blackjack.py 第 206–223 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)這段在做什麼。學習規則在 21 點裡發生的地方:一手結束才回饋。
credit_decay 的 i 次方,而 credit_decay 預設 1.0,所以每個決定一樣重。作者的註解是檔尾第二個坑:原本讓最後一個決定權重最大(0.7 的 i 次方),但爆牌那一手的最後一個決定一定是要牌、贏的那一手最後一個幾乎一定是停牌,「要牌 = 輸、停牌 = 贏」成了全面的關聯,淹沒每一格各自的教訓,模型收斂到永遠停牌;改成一樣重之後一致率才開始上升(作者在檔尾註解的原話:chart agreement started rising only after that;作者沒有附數字)。learn=True:model.py 第 137 行(第 6 節)就在這時扣增益,扣的是「這組 72 顆 KC」與「收到多巴胺的 MBON」之間的連結。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
flybrain/mb/blackjack.py 第 226–249 行(commit 004b2e3,MIT 授權;run_all.sh 會把整個 repo 放在 blackjack/repo/,同一個檔案在那裡)agreement:一致率。對 260 格的每一格:session:連打 hands 手(預設 20,000;bj2_blackjack.py 叫它時給 30,000),發牌用一個以 seed 起頭的亂數產生器(和 FlyPlayer 探索用的那個是分開的兩個)。policy)。第 252 到 261 行 reference_winrates 用同一個 play_hand 讓三種固定策略各打 20,000 手:基本策略、亂選、永遠停牌,就是 PART 3 第 4 節圖裡的三條參考線。第 265 到 295 行是作者的結果註解:他記的勝率與一致率、「它學到的是『別爆』」、以及上面提過的兩個坑。本課收在 out/upstream/blackjack_py_RESULT_comment.txt。
第三層再往下就是別人寫的程式庫,本頁不展開。另外 repo 裡有一些檔案不在 21 點這條鏈上,列在這裡讓你知道它們存在。
| 套件或檔案 | 誰用它 | 做什麼 | 進去的是什麼、出來的是什麼 |
|---|---|---|---|
| numpy | 除了 check.py 以外的每一支 Python 程式 | 一串或一張數字的運算:相乘加總(@)、排序、隨機抽樣、夾範圍 | 進出都是數字陣列 |
| scipy.sparse | fetch.py、extract.py、bj_extra.py、model.py 的 _dense | 稀疏矩陣:只存非 0 格子的表 | 進:.npz 檔;出:可以切塊、加總的矩陣 |
| pandas | fetch.py | 讀神經元屬性表(csv)、依欄篩選 | 進:csv;出:表格 |
| base64、json | bj3、每一支 | Python 內建:位元組與可印字元互轉、讀寫 JSON | — |
odour.py | 21 點沒有用到 | 把一個氣味名字變成 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 節的細胞數)。
| 檔案 | 層 | 誰叫它 | 讀什麼 | 寫什麼(本課 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 匯入它的 load | GitHub 上的兩個資料檔 | 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.json | results/bj3_author_brain.json |
bj_extra.py | 二 | run_all.sh 第 17 行 | blackjack.py、model.py、extract.py;mb_cells.json | results/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 逐塊對回原檔。