PART 2
兩個指令就能從零跑完;這一頁講清楚每個指令背後固定了哪些版本、為什麼要固定
先說本頁會一直用到的幾個詞。fly-blackjack 是 WilliamJones 在 GitHub 上公開的程式,本頁的「作者」都指他;它拿果蠅腦裡一個叫蕈狀體的區域的連結體(哪顆神經元接到哪顆、接幾個突觸的資料)去學 21 點(PART 1)。大腦檔是程式學會打 21 點之後留下來的那組數值(每一條連結的強弱),作者存成一個檔附在程式裡。種子是亂數的起始值,同一個種子每次跑出一樣的結果。KC、MBON 是蕈狀體裡的兩類神經元(PART 1 第 2 節)。腳本是一個裝著一串指令的檔案(副檔名 .sh 或 .py),下面說的「程式」「指令」多半就是它。
上面是這個專案的詞;下面是電腦操作的詞,也先認識一次:
| 詞 | 意思 |
|---|---|
| 終端機 | 打字下指令的視窗(macOS 叫「終端機」,Linux 叫 Terminal)。本課所有指令都是貼進去按 Enter |
| 套件 | 別人寫好、可以直接拿來用的 Python 程式庫,例如 numpy(數值運算)、pandas(表格) |
| conda、環境 | conda 是管理「環境」的工具;一個環境就是一份獨立的 Python 加上它自己的套件,環境之間互不干擾。本課只建一個(第 4 節) |
| pip | 在一個環境裡安裝套件的工具;本課用 conda 建環境、用 pip 裝套件 |
| repo、GitHub | GitHub 是放程式碼的網站;一個 repo(repository)就是一個專案的全部檔案與它的修改歷史。commit 是其中一次存檔的編號(第 5 節) |
下載 flyblackjack-code.zip(首頁〈需要什麼基礎〉那一格也有同一個連結),解壓縮到一個空資料夾,開終端機後打 cd 那個資料夾的路徑 進到裡面(macOS 可以把資料夾拖進終端機視窗,路徑會自己貼上)。想先確認檔案完整,可以執行 sha256sum -c SHA256SUMS.txt(第 3 節);然後依序執行:
bash setup_envs.sh # 建一個 conda 環境(只需一次)
bash blackjack/run_all.sh # BJ1–BJ3、加做檢查 X1–X4
指令裡的代號,各對應後面哪一頁的哪一步:
| 代號 | 意思 | 在哪一頁 |
|---|---|---|
| BJ1–BJ3 | 重現的三步:下載資料並切出蕈狀體、21 點 30,000 手、評分作者附的大腦檔 | PART 3 |
| X1–X4 | 作者沒做的四項檢查:加到 20 個種子、打亂哪一層接線、換 KC 選法、MBON 標記對文獻 | PART 4 |
本課在一台 Linux、12 核 CPU 的電腦上,從解壓縮開始實測:建環境 16 秒,run_all.sh 24 分 45 秒。這些程式一次只用一個核心,所以核心數不影響快慢、也不影響結果,快慢只看單一核心的速度。建環境的 16 秒是低估:它是在一台已經下載過所有套件的電腦上測的(先把原有的環境改名讓開、再從零建一次,套件直接從本機快取拿)。你的電腦若是第一次建,要把套件全部下載下來(裝好後約 499 MB),時間取決於網速,請預期比這久。
實測時間出自 out/porttest.json。這個檔和本頁其他引用的 out/… 都是本課實跑後存在課程網站 repo(github.com/marginli/bsc-flyblackjack)裡的紀錄,不必特地去看,給你對照用;不是你跑完會在自己電腦上長出來的檔案(你的結果在 results/,第 7 節)。
| 項目 | 說明 |
|---|---|
| 作業系統 | Linux 或 macOS。本課在 Linux 上跑;fly-blackjack 的 21 點把發牌與探索的亂數種子都固定了(PART 3 第 1 節),照理在另一個系統上也會得到相同數字;macOS 本課沒有實測。若在 macOS 上只有小數點末幾位不同、其他全部相同,多半是系統的浮點運算差異,不是你弄錯,第 7 節 ✗ 那格也有說 |
| conda | Anaconda 或 Miniconda 都可以(Miniconda 比較小,只含 conda 本身,建議選它);到官方網站(anaconda.com,Miniconda 的下載連結也在那一頁)下載安裝程式照步驟裝。裝好後在終端機打 conda --version,印出版本號就表示可以用 |
| git、curl | git 從 GitHub 取得程式碼,curl 下載資料檔。多數 Linux 與 macOS 已內建;打 git --version、curl --version 看有沒有印出版本號,沒有就用系統的安裝工具裝(Linux 多半是 apt,macOS 是 Homebrew;這是裝系統程式用的,和第 1 節裝 Python 套件的 pip 不同) |
| 網路與硬碟 | 跑完後下載的程式碼與資料共約 129 MB,環境約 499 MB |
| GPU | 不需要 |
硬碟用量出自 out/porttest.json。
下載包只有本課自己寫的程式。被重現的 fly-blackjack 由 run_all.sh 從 GitHub 取得並切換到固定的版本;不是不能附進來(它是 MIT 授權,允許任何人複製、修改、散布),而是故意不附:你拿到的直接來自作者公開的那個 commit,不是經過本課的副本,要核對「本課有沒有改過作者的程式」時,對著 GitHub 就能核。
| 檔案 | 做什麼 |
|---|---|
setup_envs.sh | 建一個 conda 環境,套件版本照本課實跑時固定 |
blackjack/run_all.sh | 取得 fly-blackjack;下載連結體(一整顆果蠅腦裡哪顆神經元接到哪顆的資料,這一份叫 MaleCNS)整理好的表格,從中切出蕈狀體那一塊(PART 1 第 2 節);依序跑 BJ1–BJ3、X1–X4。跑過一次之後,fly-blackjack 的程式會放在 blackjack/repo/ |
blackjack/scripts/ | 21 點實驗在作者的程式裡沒有可以直接從終端機執行的指令(沒有「命令列入口」,作者是在 Python 裡呼叫函式跑的),所以本課寫了三支小程式去呼叫作者的函式,不改作者任何一行:bj2_blackjack.py(BJ2)、bj3_author_brain.py(BJ3)、bj_extra.py(X1–X4);BJ1 直接用作者的程式,不需要 |
check.py、expected.json | 驗收:逐項比對你跑出來的數字與本課實跑的結果(第 7 節) |
SHA256SUMS.txt | 每個檔案的 SHA-256 指紋:由檔案內容算出來的一串 64 個字,內容改一個位元組就完全不同。執行 sha256sum -c SHA256SUMS.txt 會重算每個檔案的指紋並與這份清單比對,確認下載的檔案沒有損壞或被改過。每個檔案後面印 OK 就是通過;出現 FAILED 就重新下載 |
repo 的版本與下載來源寫在下載包的 blackjack/run_all.sh。
fly-blackjack 直接用到的只有三個套件,彼此沒有版本衝突,所以一個環境就夠(有些專案的套件要求互相矛盾的版本,才要分成幾個環境)。這三個套件自己還會拉進一串它們依賴的套件,所以環境裡實際裝了幾十個、約 499 MB,完整清單在下面說的 env.txt;本課只固定直接用到的三個。版本照本課實跑時固定——不是因為別的版本一定會出錯,而是重現的第一條規矩是把能固定的都固定,對不上時才知道差在哪裡。
| 環境名稱 | Python | 關鍵套件 |
|---|---|---|
flyplay_bj | 3.11 | numpy 2.4.6、scipy 1.17.1、pandas 3.0.6 |
Python 版本出自 out/porttest.json 的 python_versions;完整套件清單在 out/blackjack/env.txt。
GitHub 上的專案會一直更新,今天下載的和半年後下載的可能不是同一份程式。commit 是專案每一次存檔的版本編號(像 004b2e3 這樣一串字);run_all.sh 取得程式碼之後會切到本課用的那一版。作者日後改了程式,你跑出來的仍然是本課的那一版。
蕈狀體的連結矩陣(第 3 節說的那張表:從連結體切出蕈狀體那一塊)不是從 MaleCNS 原始資料(1.2 GB)切的,而是從另一位研究者 Yijie Yin 公開的整理版 connectome_data_prep 下載兩個檔(約 107 MB)。作者的下載程式沒有固定那個 repo 的版本,取的是它當下的主分支(最新的那一份)。技術上可以釘住版本,但本課不改作者的程式(第 3 節的原則),所以沿用他的做法:不釘版本,改靠核對。核對是作者的程式自己做的:下載完先比對兩個檔案的位元組數(78,770,675 與 28,023,979),載入時再核對神經元數、突觸數(神經元之間的接點數)、各群細胞數(蕈狀體裡幾類神經元各有幾顆)都等於作者寫死在程式裡的值,有一項不同就停下來報錯。所以日後整理版若更新,BJ1 會在這裡停住,而不是悄悄算出不同的蕈狀體;到時候要從 connectome_data_prep 的舊版本裡找回位元組數相符的那兩個檔,這一步需要會用 git 與 GitHub,不在本課的範圍;這裡只告訴你會卡在哪、原因是什麼,真遇到請找會的人幫忙或回報課程。本課沒有遇到這種情況,沒有實測。
檔案大小與核對項目出自作者的 flybrain/mb/fetch.py(flybrain 是 fly-blackjack 自己程式碼的資料夾名,不是要另外裝的套件);BJ1 下載時印出的核對行收在 out/blackjack/logs/bj1_fetch.log(PART 3 第 3 節有節錄)。
如果你曾經用 pip install --user 裝過套件,它們會被放在家目錄(你的個人資料夾,終端機裡寫成 ~)的 ~/.local 底下(打 ls ~/.local/lib,有 python3.x 開頭的資料夾就表示有);而 Python 預設會把這個資料夾也加進搜尋範圍——包括 conda 環境裡同一個版本的 Python。結果是:你以為在用環境裡固定好的 numpy 2.4.6,實際上載入的可能是 ~/.local 裡的另一個版本,而且不會有任何警告。
下載包的每一支腳本(第 1 節前面說的:裝著一串指令的檔案)都先設定 PYTHONNOUSERSITE=1,讓 Python 不去讀 ~/.local。照第 1 節的兩個指令跑就不必管它。只有當你想自己單獨重跑某一步、或改個參數試試時(例如 21 點只跑 2,000 手、只用種子 0),才需要手動下指令,這時也要在前面加上它。下面這條就是例子,要在 blackjack/repo/ 裡執行;兩個數字依序是手數與種子:
PYTHONNOUSERSITE=1 PYTHONPATH=. $(conda info --base)/envs/flyplay_bj/bin/python ../scripts/bj2_blackjack.py 2000 0
$(conda info --base) 會自動換成 conda 安裝的位置,後面接的是 flyplay_bj 這個環境自己的 Python;直接指定環境裡的 Python 來執行,就不必先用 conda activate(切換到某個環境的常見指令)。PYTHONPATH=. 是讓 Python 在目前資料夾(作者的 repo)找得到 flybrain 這個資料夾裡的程式。
numpy 2.4.6 是 flyplay_bj 環境固定的版本(out/blackjack/env.txt)。
run_all.sh 跑完會自動執行 check.py,逐項比對你的結果與本課實跑的結果,每一項印一行:
| 符號 | 意思 |
|---|---|
| ✓ | 對上了。check.py 比的對象是本課的實跑結果,不是作者的數字,所以每一項都可以要求逐位相同:作者的數字是在別台電腦、可能不同版本上跑的,只能要求接近;本課的實跑和你用的是同一套固定版本,理應一模一樣(至於你的結果和作者的數字怎麼比、算不算一致,PART 3 第 1 節會講) |
| ✗ | 對不上。後面會印出本次的值與預期的值。看到它先做兩件事:打開那一步的 logs/ 檔看最後幾行有沒有錯誤訊息(最常見是網路中斷、下載不完整);然後重跑一次 run_all.sh。還是 ✗ 的話,對照第 5 節看是不是某個版本變了;若只有小數點末幾位不同、其他全對,多半是作業系統的浮點運算差異(第 2 節),不是跑錯 |
本課的可攜測試(解到空資料夾、從建環境開始跑)最後一行是:
blackjack:17 項通過,0 項不符(共 17 項)
17 項是 17 個數字,不是 7 個步驟:一步會比對好幾個數字(例如 BJ2 四個條件各一個、X1 三個條件各一個)。
出自 out/porttest.json。開頭的 blackjack 是驗收表(expected.json)的分組名,這一包只有這一組。
跑完之後解壓縮資料夾長這樣:
解壓縮的資料夾/
├─ setup_envs.sh、check.py、expected.json、SHA256SUMS.txt、README.md
└─ blackjack/
├─ run_all.sh
├─ scripts/ 本課的三支小程式
├─ repo/ run_all.sh 取回來的 fly-blackjack(跑過一次才有)
├─ logs/ 每一步的終端輸出(跑過一次才有)
└─ results/ 每一步的數字,JSON(跑過一次才有)
想看某一步的細節,打開 blackjack/logs/:每一步一個檔案,是那一步的完整終端輸出,最後幾行通常就是結果表。所有數字另外以 JSON 存在 results/,PART 3 與 PART 4 的每一張表都標了它對應哪一個檔案。