FlapSim: A Composable MuJoCo Simulation Platform and Reduced-Order Aerodynamic Model Hierarchy for Flapping-Wing Robotics
Organizations: Department of Mechanical Engineering, School of Engineering, Institute of Science Tokyo, Tokyo, 1528550, Japan
Abstract
Flapping-wing simulation need to reconcile high-frequency wingbeat aerodynamics with the slower dynamics relevant to flight control and reinforcement learning. We present FlapSim, a modular open-source MuJoCo simulation platform that combines robot descriptions, wing geometry, and composable aerodynamic models in a deterministic simulation pipeline. Across held-out scenarios spanning frequency, gimbal, wind, frequency-step, gust, and cross-robot flat-plate regimes, we compare five reduced-order configurations operating at with a quasi-steady blade-element reference. The built-in hover cycle-averaged baseline achieves a CPU speedup but only mean wrench fidelity. Combining multirate -substep clock synchronization, three-dimensional linear/quadratic inflow and gust coupling, analytical blade-element geometry scaling, and phase-locked harmonics raises mean fidelity to at a speedup in a five-block model. A streamlined four-block model without explicit step-transient lag states achieves fidelity at a speedup. Controlled ablations show that stroke harmonics are particularly important during frequency transitions, improving held-out frequency-step fidelity by . Transfer-function analysis explains this effect: fixed-window cycle averaging retains harmonic contributions when the wingbeat frequency changes, so within-cycle reconstruction also improves the filtered wrench. These results characterize the accuracy--computation tradeoff of the aerodynamic hierarchy and identify timing, inflow, geometry, and harmonic representation as central considerations for reduced-order flapping-wing simulation. The source code are available at: https://mingshanhe.github.io/FlapSim/\href{https://mingshanhe.github.io/FlapSim/}.
Figures & tables
| Project | Physics core | Language | Subject | Aerodynamics | Learning interface |
|---|---|---|---|---|---|
| flybody [ 30 ] | MuJoCo | Python | Anatomical Drosophila body | Not described in repository | step(action) RL tasks; Acme, Ray |
| Flappy Hummingbird [ 31 ] | DART ( pydart2 ) | Python | Dual-motor hummingbird MAV | Not described in repository | Gym fwmav_hover-v0/v1 ; Stable Baselines |
| fwmav_sim_sjtu | DART | C++ (CMake), ROS | SJTU flapping wing | Port of Flappy Hummingbird | None stated |
| FlappingwingSimu [ 32 ] | Webots | Python, MATLAB | Flapping-wing biomimetic robot | QS: translational lift/drag, rotational lift, added mass | Trajectory tracking (v2.0) |
| FlapSim v0.2.0 (this report) | MuJoCo 3.8 | Python | Any URDF/MJCF/ MjSpec robot via manifest | QS reference + 3 additive models + ground-effect modifier; cycle-averaged reduced model | Gymnasium SimulationEnv ; parameter studies |
| Subpackage | Modules | Lines | Core responsibilities |
|---|---|---|---|
| flapsim.robot | 7 | 1,834 | RobotManifest , URDF/MJCF/ MjSpec import, patches, builders |
| flapsim.aero | 13 | 1,754 | Aero engine, 4 models, ground-effect modifier, atmosphere, drag, identify |
| flapsim.wings | 3 | 805 | Runtime Wing , planform integrals (profile, polyline, polygon, STL) |
| flapsim.actuators | 5 | 713 | Sinusoidal stroke, PD position, servo, DC motor + crank |
| flapsim.sensors | 6 | 623 | IMU, range finder, encoder, load cell; noise/delay conditioner |
| flapsim.fluid | 4 | 592 | Blade-element math, legacy averaged hover model, MuJoCo adapter |
| (a) Per-family results | ||||||
|---|---|---|---|---|---|---|
| Metric | Frequency | Gimbal | Wind | Step | Gust | Flat plate |
| Hover CA | ||||||
| Fidelity | 0.9275 | 0.9440 | 0.2356 | 0.4874 | 0.6153 | 0.7462 |
| Force error | 0.0838 | 0.0508 | 1.8124 | 0.6922 | 0.5810 | 0.6030 |
| Torque error | 0.0669 | 0.0647 | 1.3454 | 0.7563 | 0.4399 | 0.0184 |
| LQ wind-lag | ||||||
Appendix figures & tables4 assets
Supplementary material from the paper’s appendix.
Appendix
| Kind / category | Count | Registered identifiers and scope |
|---|---|---|
| actuator | 4 | sinusoidal_stroke (kinematic or position-only stroke), pd_position (PD or kinematic hold), servo (rate-limited lagged target), dc_motor_crank (voltage-driven motor, gearbox, crank) |
| aero | 3 | quasi_steady (single-model stack), stack (additive models and modifiers), cycle_averaged (rigid-body hover model, identified parameters) |
| atmosphere | 1 | standard (ISA density or , steady wind, /sine/step gust, Ornstein–Uhlenbeck turbulence) |
| controller | 3 | hover_pid (cascaded altitude and attitude PID), schedule (time-scheduled set points), callback (user Python function) |
| force | 1 | body_drag (quadratic drag per body axis relative to the wind) |
| recorder | 1 | memory (samples matching signals every ; export) |
| (a) Dimensional errors and per-family speedup | |||||||
|---|---|---|---|---|---|---|---|
| Model | Metric | Frequency | Gimbal | Wind | Step | Gust | Flat plate |
| Hover CA | Force RMSE ( mN ) | 1.50 | 1.52 | 37.83 | 15.14 | 16.10 | 9.25 |
| Torque RMSE ( ) | 0.086 | 0.133 | 1.966 | 1.142 | 0.847 | 0.019 | |
| Family Speedup ( ) | 65.83 | 82.09 | 65.38 | 61.97 | 60.40 | 87.20 | |
| LQ wind-lag | Force RMSE ( mN ) | 1.04 | 3.57 | 6.09 | 15.20 | 3.92 | 3.72 |
| Torque RMSE ( ) | 0.057 | 0.087 | 0.145 | 1.153 | 0.094 | 0.019 | |
| Step | Block and active features | Fit (s) |
|---|---|---|
| 1 | Pass-1 Block 1 Hover Mean ( w_m1 , 12 feat.) | 0.048 |
| 2 | Pass-1 Block 2 Gimbal Mean ( w_m2 , 27 feat.) | 0.413 |
| 3 | Pass-2 Joint Gauss–Seidel w_m1 (12 feat.) | 0.361 |
| 4 | Pass-2 Joint Gauss–Seidel w_m2 (27 feat.) | 0.364 |
| 5 | 6-Grid CV + Harmonics ( w_h1,2 , 66) + Block 3 (104) | 37.289 |
| 6 | Block 4a Steady 3D Wind (54 mean, 24 harm.) | 1.439 |
Robotics Simulation
Robotics simulation builds virtual robots and environments to model, train, and evaluate autonomous systems before real-world deployment.
See all 349 papers