BSC 專題課程 / 果蠅玩 Doom / PART 2

PART 2

準備環境與資料

兩個指令就能從零跑完整個重現;這一頁講清楚每個指令背後固定了哪些版本、為什麼要固定

← PART 1 fruitfly-lab 在做什麼 PART 3 重現 fruitfly-lab →

1兩個指令

這一頁會一直用到幾個詞,先認識一次:

詞意思
終端機打字下指令的視窗(macOS 叫「終端機」,Linux 叫 Terminal)。本課所有指令都是貼進去按 Enter
套件別人寫好、可以直接拿來用的 Python 程式庫,例如 numpy(數值運算)、vizdoom(遊戲引擎)
conda、環境conda 是管理「環境」的工具;一個環境就是一份獨立的 Python 加上它自己的套件,環境之間互不干擾。本課會建三個(第 4 節)
pip、uv在一個環境裡安裝套件的工具。pip 是最常見的,uv 是較新的同類工具;本課用 conda 建環境、用 pip 裝套件
repo、GitHubGitHub 是放程式碼的網站;一個 repo(repository)就是一個專案的全部檔案與它的修改歷史。commit 是其中一次存檔的編號(第 5 節)

下載 flydoom-code.zip(首頁〈需要什麼基礎〉那一格也有同一個連結),解壓縮到一個空資料夾,在那個資料夾裡開終端機。想先確認檔案完整,可以執行 sha256sum -c SHA256SUMS.txt(第 3 節);然後依序執行:

bash setup_envs.sh              # 建三個 conda 環境(只需一次)
bash fruitfly_lab/run_all.sh    # FF1–FF6、ViZDoom 1.3.2 對照、加做檢查 E1–E4

第二個指令裡的代號,各對應後面哪一頁的哪一步:

代號意思在哪一頁
FF1–FF6重現 fruitfly-lab 的六步:資料是同一份嗎、子圖逐位相同、子圖與全腦反應一致、校準出同樣的閾值、七個條件每一局都相同、統計PART 3
E1–E4作者沒做的四項檢查:加到 50 局、每種打亂各自校準、只讀下行神經元、右眼子圖為何偏弱PART 4

本課在一台 Linux、12 核 CPU 的電腦上,從解壓縮開始實測:建三個環境 43 秒,run_all.sh 14 分 42 秒。建環境的 43 秒要打個折:它是在一台已經下載過所有套件的電腦上測的(先把原有的三個環境改名讓開、再從零建一次,套件直接從本機快取拿)。你的電腦若是第一次建,要把三個環境的套件全部下載下來(裝好後共約 2,498 MB),時間取決於網速,請預期比 43 秒久得多。

實測時間出自 out/porttest.json。這個檔和本頁其他引用的 out/… 都是本課實跑後存在課程網站 repo 裡的紀錄,給你對照用;不是你跑完會在自己電腦上長出來的檔案(你的結果在 results/,第 7 節)。

2需要什麼

項目說明
作業系統Linux 或 macOS。fruitfly-lab 的作者在 macOS 上跑、本課在 Linux 上跑,兩邊逐局相同(PART 3 第 7 節)
condaAnaconda 或 Miniconda 都可以(Miniconda 比較小,只含 conda 本身,建議選它);到官方網站下載安裝程式照步驟裝。裝好後在終端機打 conda --version,印出版本號就表示可以用
git、curlgit 從 GitHub 取得程式碼,curl 下載資料檔。多數 Linux 與 macOS 已內建;打 git --version、curl --version 看有沒有印出版本號,沒有就用系統的套件管理工具安裝
網路與硬碟跑完後下載的程式碼與資料共約 441 MB,三個環境共約 2,498 MB
GPU不需要

硬碟用量出自 out/porttest.json。

3下載包裡有什麼

下載包只有本課自己寫的程式。被重現的專案由 run_all.sh 從 GitHub 取得,並切換到固定的版本——fruitfly-lab 的 repo 沒有授權檔(作者沒有寫明別人可以怎麼使用),法律上預設就是不能轉發,所以它的任何檔案都不能由本課散布,只能請你的電腦自己去 GitHub 取(首頁〈出處〉)。

檔案做什麼
setup_envs.sh建三個 conda 環境,套件版本照本課實跑時固定
fruitfly_lab/run_all.sh取得 fruitfly-lab 與 Shiu 等人 2024 年的全腦模型 repo(PART 1 第 2 節提過;fruitfly-lab 讀的連線表是它附的),下載 FlyWire 註解檔(每顆神經元屬於哪一種細胞類型的清單,抽子圖時靠它找出 LC10a、AOTU019 等),然後依序跑 FF1–FF6、ViZDoom 1.3.2 對照、E1–E4。
選擇性的一步:如果你另外下載了 FlyWire 官方的連線表 proofread_connections_783.feather,執行前多打一行 export FLYWIRE_FEATHER=/你的路徑/proofread_connections_783.feather,FF1 就會把兩份逐條比對(PART 3 第 3 節)。不設也沒關係:FF1 只印出 Shiu 連線表的三個數字並與本課的值核對,不會失敗
fruitfly_lab/ext/FF1 的資料核對與 E1–E4 的程式。它們把作者的程式當成程式庫來呼叫(匯入),不改作者任何一行
check.py、expected.json驗收:逐項比對你跑出來的數字與本課實跑的結果(第 7 節)
SHA256SUMS.txt每個檔案的 SHA-256 指紋:由檔案內容算出來的一串 64 個字,內容改一個位元組就完全不同。執行 sha256sum -c SHA256SUMS.txt 會重算每個檔案的指紋並與這份清單比對,確認下載的檔案沒有損壞或被改過

repo 的版本與下載來源寫在下載包的 fruitfly_lab/run_all.sh。

4三個環境

一個 conda 環境裡同一個套件只能有一個版本,而 fruitfly-lab 自己的兩個部分需要的版本互相衝突:全腦模型用的 Brian2 2.9 要 numpy 2 以前的版本(第 5 節),遊戲那一半固定的 pyarrow 26 與 numpy 2.5.4 又要 numpy 2 以後的版本,兩邊裝不進同一個環境,所以分成三個環境:全腦模型與遊戲各一個;再加一個只為了對照遊戲引擎版本的環境。setup_envs.sh 一次建好:

環境名稱Python關鍵套件給誰用
ffl_brian3.11Brian2 2.9.0、numpy 1.26.4、pyarrow 17.0.0fruitfly-lab 的抽子圖、全腦模型(FF1–FF3、E4)
ffl_doom1303.12vizdoom 1.3.0、numba 0.68.0(把神經元模擬的迴圈編譯成機器碼加速)fruitfly-lab 的遊戲(FF4–FF6、E1–E3),與作者相同的版本
ffl_doom3.12vizdoom 1.3.2、numba 0.68.0只用來做版本對照(PART 3 第 8 節)

Python 版本出自 out/porttest.json 的 python_versions;完整套件清單在 out/fruitfly/env_brian.txt、env_doom130.txt、env_doom.txt。

5三個要固定版本的地方

一、程式碼:固定到某一個 commit

GitHub 上的專案會一直更新,今天下載的和半年後下載的可能不是同一份程式。commit 是專案每一次存檔的版本編號(像 8c27fe8 這樣一串字);run_all.sh 取得程式碼之後會切到本課用的那一版(8c27fe8)。作者日後改了程式,你跑出來的仍然是本課的那一版。Shiu 的全腦模型 repo 是例外,取最新版:fruitfly-lab 只用到它附的那份連線表,而 FF1 第一步就會核對這份表的神經元數、連結數、突觸總數。本課實跑與可攜測試(把下載包解到空資料夾、從建環境開始再跑一次,第 7 節)兩次都相同;如果日後 Shiu 更新了這份表,FF1 會印 ✗,後面所有步驟就不能再拿來和本課的數字比,到時要改回舊版再跑。

二、遊戲引擎:ViZDoom 1.3.0

不指定版本的 pip install vizdoom 會裝到 1.3.2。兩個版本只差一個小版號,但遊戲本身的隨機抽樣不同,同一組種子(亂數的起點;種子相同,照理敵人的出場順序就相同)下每一局的分數都會變,連完全不用神經網路、只讀遊戲回報的敵人位置來瞄準的 oracle 條件也一樣,可見變的是遊戲本身而不是模型(PART 3 第 8 節)。所以主要的環境固定在作者用的 1.3.0,另開一個 1.3.2 的環境只做對照。

三、Brian2、numpy 與 pyarrow 的版本衝突

這裡有三個套件:Brian2 是跑神經元方程式的模擬器,numpy 是它底下做數值運算的基礎套件,pyarrow 是讀連線表那種 .feather 表格檔的套件。Shiu 的全腦模型用 Brian2 2.9,它需要 numpy 2 以前的版本;而 pyarrow 從 18 版開始需要 numpy 2 以後的版本。兩者同時裝最新版會衝突,所以 ffl_brian 把 pyarrow 固定在 17。fruitfly-lab 的 README 用 uv 裝套件(第 1 節:uv 與 pip 是同類工具,conda 則是管環境的),只註明「Brian2 2.9 需要 numpy 2 以前的版本」;本課用 pip 照同一份套件清單安裝時遇到這個衝突。

衝突的說明記在 out/fruitfly/env_notes.txt。

6一個會讓結果悄悄改變的陷阱

如果你曾經用 pip install --user 裝過套件,它們會被放在家目錄(你的個人資料夾,終端機裡寫成 ~)的 ~/.local 底下(打 ls ~/.local/lib,有 python3.x 開頭的資料夾就表示有);而 Python 預設會把這個資料夾也加進搜尋範圍——包括 conda 環境裡同一個版本的 Python。結果是:你以為在用環境裡固定好的 numpy 1.26.4,實際上載入的可能是 ~/.local 裡的另一個版本,而且不會有任何警告。

下載包的每一支腳本都先設定 PYTHONNOUSERSITE=1,讓 Python 不去讀 ~/.local。照第 1 節的兩個指令跑就不必管它。只有當你想自己單獨重跑某一步、或改個參數試試時(例如只讓完整接線的大腦玩 1 局),才需要手動下指令,這時也要在前面加上它。下面這條就是例子,要在 fruitfly_lab/repo/ 裡執行;--policy fly 是選「完整接線」那種大腦,--episodes 1 是只玩 1 局:

PYTHONNOUSERSITE=1 $(conda info --base)/envs/ffl_doom130/bin/python doom/fly_doom.py --policy fly --episodes 1

$(conda info --base) 會自動換成 conda 安裝的位置,後面接的是 ffl_doom130 這個環境自己的 Python;直接指定環境裡的 Python 來執行,就不必先用 conda activate(切換到某個環境的常見指令)。

numpy 1.26.4 是 ffl_brian 環境固定的版本(out/fruitfly/env_brian.txt)。

7跑完之後怎麼看

run_all.sh 跑完會自動執行 check.py,逐項比對你的結果與本課實跑的結果,每一項印一行:

符號意思
✓對上了。判定標準依那一項而定:逐位相同,或全腦模型那幾項在 ±20% 內(三種判定標準見 PART 3 第 1 節)
✗對不上。後面會印出本次的值與預期的值。看到它先做兩件事:打開那一步的 logs/ 檔看最後幾行有沒有錯誤訊息(最常見是網路中斷、下載不完整);然後重跑一次該資料夾的 run_all.sh。還是 ✗ 的話,對照第 5 節看是不是某個版本變了
△本課實跑時也對不上、頁面上已經說明的項目(目前只有一項,見 PART 3 第 5 節),不算失敗

本課的可攜測試(解到空資料夾、從建環境開始跑)最後一行是:

fruitfly:45 項通過,0 項不符,1 項已知不符(△,本課實跑時也一樣)(共 46 項)

開頭的 fruitfly 是驗收表(expected.json)的分組名,這一包只有這一組。

出自 out/porttest.json。

想看某一步的細節,打開 fruitfly_lab/logs/(在你解壓縮的資料夾底下;results/ 也在同一層):每一步一個檔案,是那一步的完整終端輸出,最後幾行通常就是結果表。所有數字另外以 JSON 存在 results/,PART 3 與 PART 4 的每一張表都標了它對應哪一個檔案。

← PART 1 fruitfly-lab 在做什麼 PART 3 重現 fruitfly-lab →
BSC 腦空間體研究中心 · 專題課程 果蠅玩 Doom · 教材由 Claude Code 產生 · 回課程首頁