# MaleCNS Neural Field

成年雄性果蝇连接组的 CPU 可视化实验：让模拟神经活动驱动「追食物 + 躲障碍」，观察真实连接上的活动，并在线训练外部动作读出层。

**166,700 个神经元 · 25,582,938 条固定连接 · CPU · 本地网页**

## 可以做什么

- 同时观察二维觅食场景和三维脑图，查看奖励、食物、碰撞与当前动作。
- 暂停、单步、慢放、回放；搜索神经元，追踪真实上游 / 下游连接。
- 对比离线训练读出、随机读出和规则参考，或开启在线 Double DQN 训练。
- 保存在线模型与经验回放，重启后继续训练，在独立场景中冻结模型评估。

后台模拟完整网络；网页抽样显示 **4,769 个真实位置、5,700 条真实连接**。发光与沿边粒子表示模拟活动和传播示意，不是活体记录。

## 快速开始

本机验证环境：Windows、Python 3.12、32 GB 内存、Intel Core Ultra 7 155H。无需 NVIDIA 显卡、CUDA、Node.js 或前端构建工具。数据下载约 **260 MB**，建议为环境、数据与训练记录预留数 GB 空间。

在希望保存项目的磁盘目录中打开 PowerShell：

```powershell
git clone https://github.com/Seed123-psy/male-cns-neural-field.git
cd male-cns-neural-field
py -3.12 -m venv .venv

# 把安装缓存与临时文件放在当前工作区
$env:PIP_NO_INDEX = $null
$env:PIP_CACHE_DIR = Join-Path (Get-Location) '.cache\pip'
$env:TEMP = Join-Path (Get-Location) '.cache\tmp'
$env:TMP = $env:TEMP
New-Item -ItemType Directory -Force $env:TEMP | Out-Null
.\.venv\Scripts\python.exe -m pip install -r requirements.txt --index-url https://pypi.org/simple

.\.venv\Scripts\python.exe -m flybrain download --data .\data
.\.venv\Scripts\python.exe -u server.py --port 8765
```

打开 **[http://127.0.0.1:8765](http://127.0.0.1:8765)**。首次运行需要 Numba 编译，稍等即可。按 `Ctrl+C` 停止服务。

后续可直接运行 `./start.ps1`，或 `./start.ps1 -Threads 4 -Port 8766` 调整 CPU 线程和端口。默认 8 线程，数据位于工作区 `data/`，运行缓存位于 `.cache/numba/`。如果系统阻止执行 PowerShell 脚本，使用上面的 Python 启动命令即可。

仓库包含启动所需的离线读出模型和活动校准样本。原始连接组、虚拟环境和个人在线训练检查点不上传，克隆后需执行数据下载。

## 使用页面

左侧选择动作控制器；「换场景」更换种子，「重新开始」重开当前种子。空格暂停，底部支持单步、速度调整与回放。拖动脑图旋转、滚轮缩放；点击神经元或搜索 `DNa02`、`LC10a`、`PFL3`、body ID 查看连接。

输入为青色，内部活动为白 / 紫色，输出为橙色。输入 / 输出、在线训练和模型说明默认收起，适合 1920×1080 全屏录制。

回放保存浏览器内最近约 900 帧场景与活动快照，刷新即清空。1× 演示每约 40 ms 推进一个 20 ms 模型步，实际速度受 CPU 负载影响。「脑部」是坐标裁剪，不是精细脑区 ROI。

## 在线训练

选择「在线训练 · Double DQN」或展开训练面板点击「开始」。在线读出随机初始化，通过游戏奖励学习；默认演示用的离线模仿模型是另一套权重。

| 环节 | 实现 |
|---|---|
| 输入 | 16 个左右神经群体的快 / 慢放电轨迹和平均电位，共 48 维 |
| 读出网络 | 48 → 64 tanh → 7 个转向 / 速度动作，每个动作保持 6 步 |
| 更新 | Double DQN、经验回放、目标网络、Huber loss、Adam |
| 探索 | ε-greedy，6,000 次决策中从 90% 降到 8% |
| 回放 | 容量 12,000；128 条经验后开始学习，batch 64，每条经验更新两次 |
| 奖励 | 食物 +8、碰撞 −2、超时 −3、距离进度奖励和每步时间成本 |
| 终止 | 找到食物、1,200 步超时或连续 120 步位移过小；卡住额外 −3 |

开始时使用当前场景种子（默认 23），之后自动生成 ≥10,000 的训练种子。终止后换场景并保留累计计数；重置属于环境规则。固定评估种子为 `701 / 809 / 911`，请勿手动用这些种子训练用于评估的模型。

- **保存**：写入 `runs/online/<run-id>/latest.npz`，更新 `runs/online/latest.json`。在回合结束且距离上次保存累计至少 256 条经验时自动保存；关闭服务前建议手动保存。
- **新实验**：先保存当前模型，再创建新的随机读出和 run 目录。
- **停止**：停止在线更新，切回离线读出。重启服务会载入最新检查点，默认仍使用离线模式。

检查点包含读出权重、目标网络、Adam、经验回放、随机状态和回合统计；不保存完整脑状态、场景或未完成动作。恢复后从新场景继续，不能逐帧复现中断现场。`models/training_activity.npz` 仅用于在线特征均值 / 标准差校准，不向在线模型复制老师的动作权重。

冻结最新在线读出评估（不探索、不更新）：

```powershell
.\.venv\Scripts\python.exe evaluate_online.py --steps 1800
# 也可指定某次实验
.\.venv\Scripts\python.exe evaluate_online.py --run-dir runs/online/<run-id> --steps 1800
```

结果写入 `reports/online_evaluation.json`。建议先暂停网页以减少 CPU 争用。

## 验证与评估记录

```powershell
# 游戏、在线学习、检查点、控制器接线，以及真实网络输入响应
.\.venv\Scripts\python.exe -m unittest -v test_game.py test_online.py test_server.py
# 数据校验、完整 CPU smoke test、神经元清单（会更新 reports）
.\.venv\Scripts\python.exe inspect_brain.py
# 服务启动后检查 API 与真实数据一致性
.\.venv\Scripts\python.exe verify_api.py
```

CI 运行不依赖连接组下载的在线学习和控制器测试；完整网络测试在本地下载数据后运行。前端语法可用 `node --check web/app.js` 检查，Node.js 不属于运行依赖。

离线模仿读出由规则参考提供标签，训练 10,980 条神经活动样本。历史独立测试为 3 个场景、每个控制器共 5,400 步：

| 控制器 | 食物 | 碰撞 | 奖励 |
|---|---:|---:|---:|
| 离线监督读出 | 17 | 5 | 193.38 |
| 随机读出 | 0 | 192 | −400.10 |
| 规则参考 | 12 | 75 | −9.95 |

见 [离线报告](reports/policy_training.json)。这是小规模游戏验证；规则参考在一个场景中反复碰撞，不代表普适性能。重新训练用 `train_policy.py`，仅重评估用 `train_policy.py --evaluate-only`；生成模型后重启服务加载。

[在线历史报告](reports/online_evaluation.json)记录了 11 个食物、0 次碰撞、奖励 133.11。该检查点训练时受旧版回合重置问题影响，反复使用种子 23；仓库已修复此问题，但**未重新训练并复测该成绩**。对应个人检查点未随仓库发布，报告仅作为历史观察，不能视为当前版本可直接复现的基准。

完整网络 CPU smoke test 在本机 8 线程平均约 4.8 ms / 步，首次编译约 1.5 s，仅供参考。文件 SHA-256 与规模见 [inventory.json](reports/inventory.json)。

## 科学边界与数据来源

1. **真实连接组**：MaleCNS 的细胞标注、胞体 / 胞体束位置、有向连接。`flybrain` 权重带神经递质符号、按突触后总输入归一化，不是原始突触计数。
2. **神经元模拟**：固定连接的 LIF 模型，人工感觉输入。食物方向刺激 LC10a，障碍刺激 LPLC2 / LC4；没有实现生理视觉或嗅觉。
3. **外部读出**：离线监督模仿与在线强化学习只训练动作读出层，**没有训练连接组，也没有实现突触可塑性**。特征包含直接刺激的感觉群体，尚未证明下游网络对任务的必要性。
4. **游戏规则**：二维运动、感知射线、碰撞、奖励与回合重置是人为定义。只有「规则参考」直接根据传感器计算动作。

预构建数据没有精细脑区 ROI 或神经突几何形态；superclass 不等同于脑区。本项目不声称复现真实果蝇行为。接口与神经元清单见 [INTERFACES.md](reports/INTERFACES.md)。

数据来自 [MaleCNS](https://male-cns.janelia.org/)（FlyEM / HHMI Janelia 等，CC BY 4.0），模拟库为 [flybrain / fly.ai](https://github.com/alextitonis/fly.ai)（MIT）。第三方归属、派生文件说明与许可证链接见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

## 代码结构

```text
server.py             完整 CPU 网络、HTTP API 与控制器
game.py               觅食、障碍、感知、奖励和规则参考
neural_policy.py      神经输入编码、活动特征、离线读出
train_policy.py       离线采样、模仿训练与独立评估
online_learning.py    Double DQN、训练回合、检查点
evaluate_online.py    冻结在线模型评估
web/                  HTML / CSS / Canvas，无远程前端依赖
models/               已训练离线读出和活动校准数据
reports/              数据清单、历史评估与验证记录
data/                 下载的 MaleCNS 文件（不上传）
runs/                 个人在线实验记录（不上传）
```

本地 API：`GET /api/health`、`/api/graph`、`/api/state`、`/api/search?q=DNa02`、`/api/neuron?index=332`、`POST /api/control`。服务默认仅监听 `127.0.0.1`。