Supplementary Data and Code accompanying: "A semi-empirical model of the aerodynamics of manoeuvring insect flight"

This README file provides a summary of the MATLAB files in the zipped folder SupplementaryData1.zip supplied as Supplementary Data 1 in support of the paper: Walker, S.M., Taylor, G.K. (2021). A semi-empirical model of the aerodynamics of manoeuvring insect flight, published in J. R. Soc. Interface. https://doi.org/10.1098/rsif.2021.0103 To get started, run the script "ExampleCode.m". This runs the blade element model to calculate the aerodynamic forces for two sets of kinematics: (1) the standard hovering wingbeat as defined in the paper; and (2) an example free-flight recording. Two kinematic datasets are included: "KinFourierData.mat" and "HoveringKinFourierData.mat". Both have the same structure and variables within. "KinFourierData.mat" contains all 879 recordings used in the paper (N=26,541 wingbeats), expressed in compressed form using the truncated Fourier series representation defined in the paper. "HoveringKinFourierData.mat" contains the standard hovering wingbeat as defined in the paper. Each workspace contains two structures: "Kinematics" and "Metrics". The Kinematics structure includes all of the time-varying kinematic variables reported in the paper, stored as a set of Fourier coefficients. All angles and their time derivatives are in units of degrees, degrees/s, and degrees/s^2; all linear parameters are in units of metres, metres/s, and metres/s^2. The wingbeat period ("period") is in units of milliseconds. The datasets "KinFourierData.mat" and "HoveringKinFourierData.mat" also include fields for the insectID and recording number; each structure in "KinFourierData.mat" corresponds to a single recording of a flight sequence; and each column of each variable corresponds to a single wingbeat. The "metrics" structure that accompanies the kinematic data includes several time-invariant parameters, including wing length (m), body length (m), mass (kg), and air density (rho, kg / m^3) which was calculated on the basis of the measured air temperature and humidity. The parameter "wbOffset" defines the position of the right wing base in the body-fixed axis system, normalised by body length. The workspace EristalisWingOutline.mat contains a representative wing outline for Eristalis, as measured by digitising scans of wings dissected from freshly-killed flies. The two arrays that this workspace contains specify the chordwise and spanwise coordinates of the wing outline. Each array has two columns, containing the coordinates of the leading and trailing edges, respectively. These coordinates are expressed in dimensionless form, and should be multiplied by the wing length to put them in dimensional form. The main blade element model is run using the function "blade_element_model.m". The function "conv_fourier2kinematics.m" is used to transform the Fourier coefficients of the selected sequence into a time history of the kinematic variables, with the number of time steps specified by the variable "numTimeSteps". If using other, kinematics then this function can be skipped. The function "calc_body_forces.m" is used to calculate the total forces acting on the body, based on its inertial acceleration in the lab-fixed axis system. Other functions are internal to the model. To implement the model, it is recommended that the user first runs "ExampleCode.m" to familiarise themselves with layout. This script runs two examples using the blade element model. The first example loads the "HoveringKinFourierData.mat" dataset and calculates the aerodynamic forces through the standard hovering wingbeat, with the results then plotted resolve in each of the three body axes and in the lab-fixed vertical axis. The second example loads the full dataset "KinFourierData.mat" and runs on a single selected sequence. It first calculates the total body force, and then calculates the aerodynamic forces using the blade element model. Finally, the wingbeat-averaged forces are plotted in each of the three body axes, and in the lab-fixed vertical axis. Note that when calculating the wingbeat-averaged forces, the last time step from each wingbeat is excluded. This is to avoid double-counting, and is necessary because each wingbeat is stored separately on the closed interval from phase 0 to 2*pi, such that the last time step has the same phase as the first time step, and is identical to the first time step of the following wingbeat, notwithstanding the negligible variation due to the interpolation method that is used to separate the kinematics into individual wingbeats as described in the paper.

本自述文件汇总了作为补充数据1随附的压缩文件夹SupplementaryData1.zip中的MATLAB文件，用于支撑论文：Walker, S.M., Taylor, G.K. (2021). 《操纵性昆虫飞行空气动力学的半经验模型》，发表于*J. R. Soc. Interface*。DOI链接：https://doi.org/10.1098/rsif.2021.0103。

要开始使用，请运行脚本"ExampleCode.m"。该脚本将运行叶素模型（blade element model），计算两组运动学数据对应的气动力：(1) 论文中定义的标准悬停翼拍；(2) 一例自由飞行记录。

本次提供了两组运动学数据集："KinFourierData.mat"与"HoveringKinFourierData.mat"，二者内部的结构与变量格式完全一致。其中，"KinFourierData.mat"包含论文中使用的全部879组记录（共N=26541次翼拍），采用论文中定义的截断傅里叶级数（truncated Fourier series）形式进行压缩存储。"HoveringKinFourierData.mat"则包含论文中定义的标准悬停翼拍。

每个工作区均包含两个结构体："Kinematics"与"Metrics"。其中Kinematics结构体存储了论文中报道的所有时变运动学变量，以傅里叶系数的形式保存。所有角度及其时间导数的单位依次为度（°）、度每秒（°/s）与度每二次方秒（°/s²）；所有线性参数的单位依次为米（m）、米每秒（m/s）与米每二次方秒（m/s²）。翼拍周期（"period"）的单位为毫秒（ms）。

"KinFourierData.mat"与"HoveringKinFourierData.mat"还包含了昆虫ID（insectID）与记录编号的字段；"KinFourierData.mat"中的每个结构体对应一次飞行序列的单组记录；每个变量的每一列对应一次独立的翼拍。

伴随运动学数据的"Metrics"结构体包含若干时不变参数，包括翼长（m）、体长（m）、体重（kg），以及基于实测气温与湿度计算得到的空气密度（rho, kg/m³）。参数"wbOffset"为以体长归一化后的右翼基在机体固定坐标系（body-fixed axis system）中的位置。

工作区文件EristalisWingOutline.mat包含了一只食蚜蝇（Eristalis）的典型翅膀轮廓，该轮廓通过对新鲜处死的果蝇解剖所得翅膀的扫描图像进行数字化得到。该工作区包含两个数组，分别指定了翅膀轮廓的弦向与展向坐标。每个数组包含两列，依次对应前缘与后缘的坐标。这些坐标采用无量纲形式表示，需乘以翼长以转换为有量纲单位。

主叶素模型通过函数"blade_element_model.m"运行。函数"conv_fourier2kinematics.m"用于将选定序列的傅里叶系数转换为运动学变量的时间历程，时间步数量由变量"numTimeSteps"指定。若使用自定义运动学数据，则可跳过该函数。函数"calc_body_forces.m"用于基于实验室固定坐标系（lab-fixed axis system）下的惯性加速度计算作用于机体的总作用力。其余函数为模型内部工具。

为顺利实现该模型，建议用户首先运行"ExampleCode.m"以熟悉整体流程。该脚本通过叶素模型运行两个示例：第一个示例加载"HoveringKinFourierData.mat"数据集，计算标准悬停翼拍的气动力，并将结果分别在三个机体轴与实验室固定垂直轴上进行绘图展示。第二个示例加载完整数据集"KinFourierData.mat"并针对单组选定序列进行运算：首先计算总机体力，随后通过叶素模型计算气动力。最终，将在三个机体轴与实验室固定垂直轴上绘制翼拍平均力的分布曲线。

需要注意的是，在计算翼拍平均力时，将排除每个翼拍的最后一个时间步。此举旨在避免重复计数，这是由于每个翼拍均存储于相位区间[0, 2π]的闭合区间内，最后一个时间步的相位与第一个时间步完全一致，且与下一个翼拍的第一个时间步几乎完全相同（尽管由于论文中所述的将运动学拆分为独立翼拍的插值方法会存在可忽略的差异）。