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 48 held-out scenarios spanning frequency, gimbal, wind, frequency-step, gust, and cross-robot flat-plate regimes, we compare five reduced-order configurations operating at 1ms with a 50μs quasi-steady blade-element reference. The built-in hover cycle-averaged baseline achieves a 67.51× CPU speedup but only 0.6593 mean wrench fidelity. Combining multirate 21-substep clock synchronization, three-dimensional linear/quadratic inflow and gust coupling, analytical blade-element geometry scaling, and phase-locked 1f–6f harmonics raises mean fidelity to 0.9646 at a 65.19× speedup in a five-block model. A streamlined four-block model without explicit step-transient lag states achieves 0.9662 fidelity at a 67.98× speedup. Controlled ablations show that stroke harmonics are particularly important during frequency transitions, improving held-out frequency-step fidelity by +0.3176. 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
TABLE I: Open flapping-wing simulators compared in this report, described only with facts stated in their repositories or cited papers. QS: quasi-steady blade-element aerodynamics.
Fig. 2: FlapSim architecture and aerodynamic model hierarchy. (a) Robot descriptions and wing geometry are assembled into a MuJoCo 3.8 simulation, with a deterministic sequence of sensing, control, actuation, force evaluation, integration, post-step updates, and recording. Plugins exchange state through a shared signal bus. (b) The hierarchy connects the 50μs blade-element reference to alternative 1ms reduced models ( 65×–68× speedup). Dashed connections denote offline identification.
TABLE II: Deterministic software inventory of FlapSim v0.2.0 (commit 19fa57f ) across its 13 subpackages and root namespace ( 69 Python modules, 9,177 lines, 17 registered plugins, 117 tests across 23 test files, 22 docs, 24 examples).
(a) Per-family results
Metric
Frequency
Gimbal
Wind
Step
Gust
Flat plate
Hover CA
Fidelity M
0.9275
0.9440
0.2356
0.4874
0.6153
0.7462
Force error eF
0.0838
0.0508
1.8124
0.6922
0.5810
0.6030
Torque error eτ
0.0669
0.0647
1.3454
0.7563
0.4399
0.0184
LQ wind-lag
TABLE III: Held-out benchmark results for five 1ms configurations against the 50μs blade-element reference. (a) Fidelity M , normalized force error eF , and normalized torque error eτ for each of six regimes ( 8 scenarios each). (b) Mean fidelity Mˉ=S over all 48 scenarios, CPU speedup, and offline training time.
Fig. 3: Wrench fidelity across the aerodynamic model hierarchy. (a) Mean fidelity in each flight regime ( n=8 scenarios per regime). (b) Mean fidelity across all 48 scenarios, increasing from 0.6593 for the hover cycle-averaged baseline to 0.9662 for the four-block harmonic model. Error bars represent ±1 sample standard deviation across scenarios: n=8 in (a), and n=48 in (b). The plotted scenario-level values are from a local re-evaluation; family means agree with the original benchmark in Table III within 0.001 . The bars describe scenario variability, rather than uncertainty across repeated runs.
Fig. 4: Force and torque errors by flight regime. (a) Normalized force error eF . (b) Normalized torque error eτ . Both axes are logarithmic. The original benchmark records a 50.1× wind force-error reduction ( 1.8124→0.0362 ) and a 27.3× flat-plate force-error reduction ( 0.6030→0.0221 ). Points and error bars show means and ±1 sample standard deviation across the 8 scenarios per regime in the local re-evaluation.
Fig. 5: Computational speedup and component ablations. (a) CPU speedup by regime, relative to the reference simulator; the dashed line marks the 20× score-saturation threshold. Points and error bars show means and ±1 sample standard deviation across the 8 scenarios per regime in the local re-evaluation. Original benchmark family speedups span 52.07× to 109.85× . (b) Changes in frequency-step and overall fidelity when removing harmonics, explicit transient states, or clock synchronization. Frequency-step changes are −0.3176 , +0.0095 , and −0.3243 , respectively. Panel (b) shows aggregate benchmark differences and has no error bars; the clock comparison uses the completed pre- and post-synchronization runs described in the text.
Fig. 6: Harmonic reconstruction and moving-average filter leakage. (a) Raw and cycle-filtered three-dimensional force RMSE. Harmonic synthesis reduces raw RMSE by 6.65× ( 0.4166N→0.0627N ). (b) Mean-only and harmonic-model fidelity by regime in the original post-hoc evaluation. The frequency-step improvement is +0.3680 , consistent with cancellation of the 244.2× increase in fundamental-frequency transmission at fhigh . Values are aggregate results; neither panel displays standard-deviation bars.
Fig. 7: Force–torque asymmetry and fidelity dispersion. (a) Mean scenario-wise error ratio eF/eτ with ±1 sample standard deviation ( n=8 per regime). (b) Minimum–maximum ranges (lines) and medians (points) of the five-block model’s fidelity across those scenarios. Both panels use the local re-evaluation. The original post-hoc evaluation discussed in the text is a separate record: 100% of scenarios below its bottom-decile threshold P10=0.9435 are frequency-step cases, with a minimum of 0.8924 at scenario #28. The starred lower SD bar for the hover baseline in the flat-plate regime crosses zero and is displayed at 0.001 times its mean on the logarithmic axis; its upper SD is unchanged.
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)
standard (ISA density or ρ , steady wind, 1−cos /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 Δt ; export)
Appendix
TABLE IV: Complete registry of FlapSim v0.2.0 plugins ( 17 across 7 kinds), aerodynamic models ( 4 ) and modifiers ( 1 ), shipped robot descriptions, and verification suite.
(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 ( mN⋅m )
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 ( mN⋅m )
0.057
0.087
0.145
1.153
0.094
0.019
Appendix
TABLE V: Cycle-filtered errors and runtime over 48 held-out scenarios; 5-block and 4-block denote harmonic models. Force/torque RMSE units are mN / mN⋅m ( 10−3N / 10−3N⋅m ). CPU speedup uses the blade-element reference.
Fig. 8: Ridge-regression weight norms and sensitivity to the phase model. (a) Frobenius weight norm ∥W∥F by identification stage. Subtracting the Block 1–2 harmonic predictions before Step 5 avoids a 5.13× increase in weight norm ( 0.9920 for the five-block model versus 5.0885 without harmonics). (b) Held-out frequency-step cross-validation fidelity for six combinations of phase convention (direct phase, or continuous phase at nominal or synchronized rate) and harmonic sample weight ( 1.5 or 3.0 ). Points are the recorded fit results; no standard-deviation bars are shown.
School of Engineering and Computing, Christopher Newport University · Department of Mathematics and Statistics, Texas Tech University · Department of Computer Science, Texas A&M University-Corpus Christi