flybrain-sim · MaleCNS 果蝇脑-身体闭环仿真实验台

一句话介绍：
从 MaleCNS 果蝇连接组提取神经元子图，用 Brian2 做脉冲仿真，再接入 FlyGym / MuJoCo 虚拟果蝇身体，形成一个可交互的“脑反应 → 身体运动”闭环实验台。

GitHub 仓库：https://github.com/Sylviali-Maker/flybrain-sim

0.1 项目定位

这是一个 本地科研演示与教学实验台，不是通用全脑仿真器，也不是真实活体果蝇实验。

它回答一个很具体的问题：

外界刺激（食物 / 天敌）
    ↓
感觉输入神经元放电
    ↓
连接组子图中的神经元活动扩散
    ↓
中心神经元 DNge104_R 是否放电
    ↓
前进 / 停止决策
    ↓
FlyGym 步态控制器驱动虚拟果蝇腿部运动
    ↓
MuJoCo 物理身体产生位移和姿态变化

0.2 核心亮点

1. 连接组数据驱动
   从 neuPrint 的 male-cns:v1.0 数据集中抓取 DNge104_R 及其直接上下游伙伴，默认构建 166 神经元 / 291 连接 的可控子图。

2. 神经元级仿真
   使用 Brian2 运行 LIF 脉冲神经网络，输出 spike 时间、raster 图和逐周期统计。

3. 脑-身体闭环
   Brian2 的中心神经元 spike 决定 GO / NO-GO，再由 FlyGym 的 side-specific locomotion controller 展开为左右侧身体控制信号。

4. 虚拟果蝇主视角
   FlyGym + MuJoCo 渲染 480 × 640 主相机画面，每个 100ms 闭环周期播放 4 帧，能直接看到虚拟果蝇身体和腿部运动。

5. 教学式因果链
   页面把控制链路拆成 6 个阶段：
   刺激源 → 感觉输入 → 脑网络反应 → 中心神经元决策 → 身体控制信号 → 身体执行

6. 食物 / 天敌双刺激源
   可以在小型俯视图中拖动食物和天敌；天敌刺激优先，用于观察不同外界条件下的脑-身反应。

7. 无需 GPU / Docker
   本项目在普通 Windows 机器上运行，不使用 CUDA，也不依赖 Docker。

0.3 项目截图

果蝇本体主视角

神经元骨架

Brian2 raster

0.4 这是什么 / 不是什么

• 这是 FlyGym + MuJoCo 的虚拟果蝇身体模型
• 不是真实活体果蝇实验
• Brian2 子网络输出的是“前进 / 停止”决策
• 腿部动作由 FlyGym 步态控制器展开，不是 166 个神经元直接控制每块肌肉
• 当前版本是 阶段 10 · 本地互动实验台，不是 MaleCNS 全脑实时仿真

1. 项目目标

1. 从 neuPrint 的 male-cns:v1.0 数据集中抓取指定神经元及其直接上下游连接
2. 构建可控规模的连接组子图
3. 用 Brian2 运行确定性的 LIF 仿真
4. 建立感觉-运动闭环协议
5. 用 FlyGym 把神经输出映射为果蝇身体运动
6. 输出可复现的实验报告、事件日志和轨迹数据
7. 提供本地互动实验台，让用户改变食物 / 天敌刺激源，并观察“刺激 → 感觉输入 → 脑网络 → 中心神经元 → 身体控制信号 → 身体执行”的完整因果链

2. 运行环境

项	要求 / 状态
操作系统	Windows
Python	3.12.13
包管理	uv
GPU	无需 CUDA；本机 Intel UHD 730 已验证可跑 FlyGym
内存	32GB
网络	需要访问 neuPrint
Docker	不需要
付费服务	不使用

3. 依赖

已锁定：

• brian2>=2.10.1
• flygym>=2.1.0
• navis>=1.12.0
• neuprint-python>=0.6.3

安装依赖：

uv sync

校验依赖锁定：

uv lock --check

4. neuPrint token 配置

网络抓取阶段需要 NEUPRINT_APPLICATION_CREDENTIALS 环境变量。

如果新终端里没有该变量，用下面命令设置（替换成你自己的 token，不要提交到仓库）：

setx NEUPRINT_APPLICATION_CREDENTIALS "your-neuprint-token"

设置后需要重启终端再运行。

5. 快速开始

说明：main.py 是项目脚手架占位文件，不作为阶段入口；本项目的阶段入口是 01～08 脚本。

5.1 校验 neuPrint 连接

uv run python .\01_check_token.py

输出：

• outputs\connection\connection_report.json

5.2 抓取神经元与连接

uv run python .\02_fetch_neuron.py --query DNge104

或直接使用 bodyId：

uv run python .\02_fetch_neuron.py --body-id 12781

输出：

• outputs\neurons\DNge104_R_12781_neuron.json
• outputs\neurons\DNge104_R_12781_connections.csv
• outputs\neurons\DNge104_R_12781_report.json

5.3 绘制骨架图

uv run python .\03_plot_skeleton.py --body-id 12781

输出：

• outputs\skeletons\DNge104_R_12781_skeleton.png

5.4 构建子图

默认 200 节点上限：

uv run python .\04_build_subgraph.py --body-id 12781 --max-nodes 200

1000 节点上限基准：

uv run python .\04_build_subgraph.py --body-id 12781 --max-nodes 1000 --output-dir outputs/benchmarks/subgraph_1000

输出：

• outputs\subgraphs\DNge104_R_12781_nodes.csv
• outputs\subgraphs\DNge104_R_12781_edges.csv
• outputs\subgraphs\DNge104_R_12781_subgraph.json
• outputs\subgraphs\DNge104_R_12781_summary.json

5.5 Brian2 LIF 仿真

uv run python .\05_brian2_lif_sim.py

输出：

• outputs\simulations\DNge104_R_12781_spikes.csv
• outputs\simulations\DNge104_R_12781_raster.png
• outputs\simulations\DNge104_R_12781_summary.json

5.6 离线感觉-运动闭环

uv run python .\06_closed_loop_sim.py

输出：

• outputs\closed_loop\DNge104_R_12781_events.jsonl
• outputs\closed_loop\DNge104_R_12781_report.md

5.7 Brian2 → FlyGym 物理闭环

uv run python .\07_flygym_bridge.py

默认运行：

• 100 个 Brian2 闭环周期
• 100,000 个 FlyGym 物理步
• 1ms 轨迹采样

输出：

• outputs\flygym\DNge104_R_12781_trajectory.csv
• outputs\flygym\DNge104_R_12781_bridge_frame.png
• outputs\flygym\DNge104_R_12781_bridge_report.md
• outputs\closed_loop\DNge104_R_12781_flygym_events.jsonl

本机实测耗时约 166s，适合验证，不适合频繁交互式调试。

5.8 本地互动实验台：果蝇本体主视角 + 脑-身体因果链

启动：

uv run python .\08_interactive_lab.py --port 8765

打开：

• http://127.0.0.1:8765/

主画面：

• 480 × 640 FlyGym 相机分辨率，实际渲染为 640 × 480
• 每个闭环周期渲染 4 帧，按 30fps 播放
• 不显示“正在计算”遮罩，计算期间保留上一帧
• 页面明确标注这是 FlyGym + MuJoCo 虚拟果蝇，不是真实活体

页面功能：

• 拖动 食物 和 天敌 两个刺激源
• 天敌刺激优先级高于食物
• 调整外界刺激强度
• 单步执行 100ms 神经-身体闭环
• 连续跑 / 暂停 / 重置
• 查看轨迹、目标距离、中心神经元 spike、全网络 spike 和身体运动

教学因果链：

① 刺激源
    食物 / 天敌 / 无刺激

② 感觉输入
    20 个输入神经元，当前放电率 xx Hz

③ 脑网络反应
    166 个神经元，全网络 spike xx

④ 中心神经元决策
    DNge104_R spike = x
    x = 0 → NO-GO / HOLD
    x > 0 → GO / MOVE

⑤ 身体控制信号
    右侧 / 左侧信号强度，进度条显示

⑥ 身体执行
    FlyGym + MuJoCo 腿部运动

高级视图：

• 保留 166 行全网络 raster
• 标记 20 个感觉输入神经元
• 标记 中心神经元 DNge104_R
• 保留中心神经元最近 20 个周期的 spike 折线

默认使用当前 200-cap 子图（166 个神经元 / 291 条连接）。

本机实测一次单步约 0.8～2.0s。480 × 640 分辨率下约为 2s，不是 60fps 游戏式实时。如果更看重交互速度，可以把 08_interactive_lab.py 里的 camera_res=(480, 640) 调回 camera_res=(240, 320)。

本地接口：

• GET /state
• POST /step
• POST /reset

这些接口只绑定 127.0.0.1，不访问外网。

6. 闭环协议

事件日志使用 JSON Lines，每行一个事件，共四类：

1. sensory_event：环境状态与感觉刺激
2. spike_event：Brian2 spike 时间与神经元标识
3. motor_event：中心神经元输出解码后的动作
4. environment_feedback：动作后的环境状态与下一轮刺激

动作映射：

阶段 6 动作	FlyGym descending signal
move_forward	[1.0, 1.0]
hold	[0.0, 0.0]

时间映射：

• 1 个 Brian2 闭环周期 = 100ms
• 1 个周期 = 1000 个 FlyGym 物理步
• 100 个周期 = 100,000 个物理步

7. 规模基准结果（阶段 8 + 阶段 9）

用例	节点上限	实际节点	连接数	spike 数	活跃神经元	墙钟耗时	峰值内存
200-cap	200	166	291	208	21	10.6537457s	—
1000-cap	1000	738	1293	219	21	10.6197058s	—
1000-cap（阶段 9 复测）	1000	738	1293	219	21	10.2977955s	188.520MB
2000-cap	2000	1452	2388	230	21	10.5780902s	189.848MB
5000-cap	5000	2252	3330	236	21	10.4732296s	190.066MB
10000-cap 挑战	10000	2252	3330	236	21	10.4732296s	190.066MB

结果文件：

• outputs\benchmarks\stage8_scale_results.csv
• outputs\benchmarks\stage8_scale_benchmark.md
• outputs\benchmarks\scale_results.csv
• outputs\benchmarks\scale_benchmark.md

说明：

• 实际节点数受 DNge104_R 直接上下游伙伴数量限制。
• 10000-cap 与 5000-cap 返回同一张 2252 节点图，说明当前直接连接策略已达可用伙伴上限。
• 若要继续扩展到 10000 以上，需要引入多跳子图、更换中心神经元或改用 NEST / 分布式方案。
• MaleCNS 全脑动态仿真仍列为远期扩展，不作为本机交付承诺。

8. 阶段 7b FlyGym 桥接结果

• 闭环周期：100
• FlyGym 物理步：100,000
• 事件总数：418
• sensory_event：100
• spike_event：118
• motor_event：100
• environment_feedback：100
• move_forward：3 个周期
• hold：97 个周期
• c_thorax 轨迹首末采样 x 位移：4.009283549852169mm
• 事件级初始状态到位移终点：4.010353546179138mm
• 3.0mm 物理目标：已到达
• 事件 ID 连续：true
• 时间戳非递减：true
• FlyGym 命令与动作匹配：true

9. 输出目录

目录	内容
outputs\connection	neuPrint 连接校验报告
outputs\neurons	神经元元数据和上下游连接
outputs\skeletons	骨架可视化 PNG
outputs\subgraphs	子图节点、边、JSON 和摘要
outputs\simulations	Brian2 spike 与栅格图
outputs\closed_loop	离线闭环和 FlyGym 扩展事件日志
outputs\flygym	FlyGym 轨迹、截图和报告
outputs\benchmarks	阶段 8 / 9 规模基准
outputs\acceptance	阶段 8 验收报告

10. 安全与限制

• 不把 token 写入代码、日志或输出
• 不使用 Docker
• 不使用 CUDA / GPU
• 不使用付费服务
• 不宣称本机支持 MaleCNS 全脑实时仿真
• 互动实验台仅绑定 127.0.0.1，是约秒级响应的科研实验台，不是 60fps 游戏式实时系统
• 互动实验台是 虚拟果蝇模型，不是真实活体果蝇实验
• 互动实验台默认使用 200-cap 演示子图，优先保证交互可用性
• 阶段 8 基准最高到 1000-cap（实际 738 节点）
• 阶段 9 已扩展到 5000-cap / 10000-cap 挑战，当前直接连接策略实际稳定上限为 2252 节点 / 3330 连接
• 全脑动态仿真列为远期扩展，不属于本机第一版交付承诺

11. 推荐阅读

• docs\03-development-plan.md
• outputs\acceptance\stage8_acceptance_report.md
• outputs\flygym\DNge104_R_12781_bridge_report.md
• outputs\closed_loop\DNge104_R_12781_report.md