flybody项目详解:Google DeepMind与Janelia打造的果蝇全身物理仿真平台(Nature论文开源)
flybody项目详解:Google DeepMind与Janelia打造的果蝇全身物理仿真平台(Nature论文开源)
flybody 是由 Google DeepMind 与 HHMI Janelia 研究园区联合开发的果蝇(Drosophila melanogaster)全身物理仿真平台,基于 MuJoCo 物理引擎构建,随 2025 年发表于 Nature 的论文《Whole-body physics simulation of fruit fly locomotion》正式开源。它提供了一套解剖学级别的果蝇刚体模型,以及飞行模仿、行走模仿、球上行走、视觉引导飞行等开箱即用的强化学习(RL)任务环境,是研究果蝇生物物理与神经运动控制的理想起点。
左:按真实解剖结构渲染的果蝇模型;右:flybody 用于物理仿真的简化多刚体模型,包含头部、胸部、腹部、翅膀、平衡棒与六足等部件。
为什么需要 flybody:从动画到真实物理 🦟
传统果蝇三维模型多用于可视化,无法模拟真实的力、接触与空气动力学效应。flybody 的核心价值在于:
- 解剖学细节:模型由 Blender 几何模型经网格转换、部件融合(fuse)流程生成,涵盖复眼、触角、口器、翅膀膜、平衡棒(haltere)、八节腹部与带爪的跗节等结构,源网格与构建脚本均保留在 flybody/fruitfly/build_fruitfly/ 中,流程说明见 flybody/fruitfly/build_fruitfly/README.md。
- 物理级运动控制:59 维动作空间覆盖腿部、翅膀、头部、触角、腹部等动作类别,可分别启用/禁用(见 flybody/fruitfly/fruitfly.py 中的
_ACTION_CLASSES)。 - 空气动力学建模:翅膀的气动阻力由 MuJoCo 椭球流体模型计算,flybody/ellipsoid_fluid_model.py 将其用 Python 完整重写,便于分析升力、阻力、Magnus 力等各分量。
- 完整 RL 训练栈:内置基于 TensorFlow/Acme 的 DMPO 智能体与 Ray 分布式训练脚本,无需自己搭训练框架。
项目结构:3分钟看懂 flybody 的目录布局
| 目录 / 文件 | 作用 |
|---|---|
| flybody/fruitfly/assets/ | 果蝇模型核心资产:fruitfly.xml(MJCF 主模型)、floor.xml 及全部 .obj 网格 |
| flybody/tasks/ | RL 任务定义:飞行模仿、行走模仿、球上行走、视觉飞行、奖励函数、轨迹加载器等 |
| flybody/agents/ | DMPO 智能体、网络工厂、Ray 分布式训练组件 |
| flybody/train_dmpo_ray.py | 分布式 RL 训练入口脚本 |
| flybody/fly_envs.py | 任务环境工厂函数,一行代码创建环境 |
| docs/ | Jupyter Notebook 教程(入门、环境示例、视觉飞行控制器复用等) |
| tests/ | pytest 测试套件 |
快速上手:5步让果蝇动起来 🚀
第 1 步:克隆仓库并创建 conda 环境
git clone https://gitcode.com/gh_mirrors/fl/flybody
cd flybody
conda create --name flybody -c conda-forge python=3.10 pip ipython cudatoolkit=11.8.0
conda activate flybody
第 2 步:按需求选择安装模式(依赖定义见 pyproject.toml)
pip install -e . # 核心版:仅物理仿真与任务原型
pip install -e .[tf] # ML 扩展:加入 TensorFlow、Acme,支持策略推理
pip install -e .[ray] # Ray 扩展:在 ML 扩展基础上支持分布式训练
第 3 步:零代码体验模型 —— 把 flybody/fruitfly/assets/ 下的 fruitfly.xml 或 floor.xml 直接拖入 MuJoCo 的 simulate 查看器即可看到果蝇。
第 4 步:用 Python 跑一个行走模仿环境(核心版安装即可运行):
import numpy as np
from flybody.fly_envs import walk_imitation
env = walk_imitation()
for _ in range(100):
action = np.random.normal(size=59) # 59 维行走动作
timestep = env.step(action)
pixels = env.physics.render(camera_id=1) # 渲染一帧
第 5 步:可选配置 —— 无显示环境下设置 MUJOCO_GL=egl 等 MuJoCo 渲染变量;ML/Ray 扩展可能需要补充 LD_LIBRARY_PATH(详见 README.md 的 "Additional configuring" 一节)。装完可运行 pytest 验证核心组件。
内置任务环境:飞行、行走与视觉引导
所有环境工厂函数集中在 flybody/fly_envs.py,基于 dm_control 的 composer.Environment 统一封装:
- 飞行模仿(
flight_imitation,flybody/tasks/flight_imitation.py):果蝇追踪一条真实飞行参考轨迹("幽灵果蝇"),翅膀由拍翅节律生成器(WingBeatPatternGenerator)驱动,腿部可自动收起。 - 行走模仿(
walk_imitation,flybody/tasks/walk_imitation.py):跟踪真实行走轨迹的相位空间,翅膀默认禁用。 - 球上行走(
walk_on_ball,flybody/tasks/walk_on_ball.py):果蝇系留在一个悬浮大球上行走,用于研究足端附着力(adhesion)控制。 - 视觉引导飞行(
vision_guided_flight,flybody/tasks/vision_flight.py):在正弦凸起(bumps)或沟槽(trench)地形中飞行避障,撞地即终止,考验视觉反馈能力。 - 模板任务(
template_task,flybody/tasks/template_task.py):无操作的空任务,适合开发自定义任务与传感器实验。
奖励设计见 flybody/tasks/rewards.py(含 deep-mimic 风格的深度模仿奖励项),地形竞技场在 flybody/tasks/arenas/,HDF5 参考轨迹加载器在 flybody/tasks/trajectory_loaders.py。参考轨迹数据集需自行下载(见 flybody/download_data.py)。
训练流程:DMPO 智能体 + Ray 分布式训练 🧠
训练入口是 flybody/train_dmpo_ray.py,其设计要点:
- 智能体采用 DMPO(Acme 库中的 TensorFlow 实现),核心配置集中在
DMPOConfig数据结构中,便于调参; - 训练循环、Learner、ReplayServer 与 EnvironmentLoop 的 Ray 分布式拆解见 flybody/agents/ray_distributed_dmpo.py;
- 脚本不绑定特定任务——替换
environment_factory中的环境即可训练飞行、行走等其他任务; - 轻量验证:加
--test参数可单 actor 跑训练,每 10 秒打印一次统计信息,适合先小规模试跑。
适合谁使用,能做什么
flybody 定位是果蝇生物物理仿真平台 + 具身神经控制建模工具,适合以下场景:
- 神经科学 / 生物物理研究:在真实物理环境中研究果蝇运动控制、附着力、气动机理;
- 强化学习研究:直接复用其模仿学习(deep-mimic)任务范式,或基于
template_task开发新任务; - 教学与原型开发:Notebook 教程(docs/getting-started.ipynb、docs/fly-env-examples.ipynb)可快速带新手跑通完整流程。
如果你在学术工作中使用了 flybody,请按 README.md 中的 BibTeX 条目引用其 Nature 论文(Nature, 643, 1312–1320, 2025)。
