JSBSim飞行仿真三件套配置与命令行调参排错指南

很多人第一次跑 JSBSim，卡住的地方往往不是气动系数写错，而是三个文件之间的引用关系没理顺：机型定义文件被找到，但引擎文件没找到；脚本跑了，但初始条件被覆盖；输出日志生成了，列名却全是零。JSBSim 的运行文件体系说白了就是一套"谁引用谁、谁覆盖谁"的约定，机型定义 XML、初始条件与脚本 XML、输出与日志配置这三件套各管一段，任何一段的角色错位，结果就是仿真能启动、数据不可用。这篇内容围绕这三件套的配置逻辑和命令行调参展开，把文件结构、加载顺序、属性路径、单位换算、常见静默失败逐条拆开，适合刚接触这类飞行动力学模型工具、准备自己搭一条仿真流水线的开发者，也适合已经能跑起来、但被"数据对不上"折磨过一阵的人。

1. 三件套的职责边界先划清楚

1.1 为什么"能跑起来"不等于"配对成功"

飞行动力学模型的运行过程，本质是把一堆物理参数按时间步推进，每一步都要读取气动系数、推力、质量特性、操纵量，再回写状态量。JSBSim 把这些参数组织成一棵属性树，所有计算都是对属性树节点做读写。机型定义文件负责建树和定义计算规则，初始条件负责给树叶节点赋初值，脚本负责在时间轴上安排事件，输出配置负责在每一步挑一部分节点落盘。四件事各有归属，混在一起就会出现"树建好了但值没赋上"或者"值赋上了但被后面的重置冲掉"。

我见过最常见的误判，是把机型定义文件当成"完整的飞机"，以为只要这个文件对，仿真结果就必然对。实际上机型文件里几乎不写初始高度、初始速度、初始姿态，这些统统来自初始化环节；而初始化环节又会被脚本里的<reset>、命令行--trim、以及--property覆盖。加载顺序大致是：先按机型名找到 FDM 配置并建树，再执行初始化赋值，接着执行脚本里的 pre-load 与 run 段，运行过程中命令行属性注入和事件条件交替生效。搞不清这个顺序，调参就是瞎猜。

注意：机型定义文件里<fdm_config name="...">的 name 属性，才是脚本<use aircraft="...">里要写的值。文件名和这个 name 不一致时，脚本会找不到模型，但报错信息往往只提示"无法加载"，不会告诉你两者不匹配。

1.2 三件套的对照关系

把三件套的职责摊成一张表，比读十页文档管用：

这张表里最容易被忽略的是最后一行。属性路径拼错在 JSBSim 里通常不会抛异常，它只会返回一个默认值，通常是 0 或者保持上一次的值。于是你打开 CSV，看到一整列 0，以为是模型没算，其实是路径名多了一个横杠。

1.3 目录约定比参数更重要

JSBSim 的路径解析有一套默认约定：机型定义文件放在aircraft/目录下，与它同名的子目录里放引擎、螺旋桨、系统、初始条件这些附属文件。机型文件里写<engine file="demo-engine">，实际查找的是aircraft/demo/demo-engine.xml；写<system file="demo-systems">，找的是aircraft/demo/demo-systems.xml。这个约定省掉了大量路径书写，但也意味着你把文件挪个位置就全线崩。

我的做法是固定一个工作根目录，机型文件、附属目录、脚本、日志指令文件全部放在这个根下，命令行里用绝对路径或者从根目录启动。Windows 上尤其注意路径里的空格和非 ASCII 字符，某些构建版本对这两者处理不一致，最稳妥的方式是把工程目录放在纯英文无空格的路径下。

2. 机型定义文件：属性树的骨架怎么搭

2.1 根节点与单位制，所有坑的起点

机型定义文件的根节点是<fdm_config>，带name、version、release三个属性。name用于被脚本引用，version通常是 2.0 之类的格式版本号。根节点下面按固定顺序排列若干段：<metrics>几何参数、<mass_balance>质量与惯量、<ground_reactions>起落架、<propulsion>动力、<flight_control>飞控通道、<aerodynamics>气动、<system>外部系统、<input>输入映射、<output>输出定义。顺序本身不强制，但阅读和维护时按这个顺序写，出问题时定位快得多。

单位制是绕不开的第一道坎。JSBSim 内部计算全部使用英制：长度英尺、质量 slug、力磅、力矩磅英尺、压力 psf、速度英尺每秒。XML 里每个数值节点几乎都必须带unit属性，写unit="FT"、unit="LBS"、unit="SLUG*FT2"、unit="IN"这类表达式，解析器会在读入时统一换算。不带unit的节点在部分版本里会按默认单位处理，在另一些版本里直接报错，行为不一致，所以我的习惯是每个数值节点都显式写单位，一个不漏。

提示：惯量单位常写成SLUG*FT2，如果误写成KG*M2而数值又按公制填，惯量会差出一个数量级以上，表现出来就是俯仰响应快得离谱或者姿态直接发散。这类错误不会报错，只能靠数值合理性反查。

换算关系记几个常用的：1 英尺 = 0.3048 米，1 磅 = 0.4536 千克，1 slug = 32.174 磅，1 psf = 47.88 帕。填参数时先在纸上把公制换算成英制再写进 XML，不要在脑子里现场换，出错率极高。

2.2 几何参数与质量特性，数字对不上后面全白费

<metrics>段定义参考面积、翼展、弦长、平尾面积与力臂、垂尾面积与力臂，以及若干参考点位置。参考面积wingarea直接进入升力公式，翼展进入滚转力矩和展弦比计算，平尾力臂进入俯仰力矩。这几个数字错一个，配平结果就整体偏移。

<mass_balance>段定义空重、重心位置、三个轴向惯量、叉积惯量，还可以挂若干pointmass表示乘员、载荷、燃油之外的固定配重。重心位置的 x 坐标基准是机头参考点，单位为英寸时常见写法是<location name="CG" unit="IN"><x>40.0</x><y>0</y><z>0</z></location>。重心位置变化会同时影响静稳定性和配平舵量，改动之后必须重跑配平，不能沿用旧的舵量。

我踩过的一个坑是空重和载荷重复计算。机型文件里写了emptywt，初始化里又写了一次weight，两者叠加，飞机比预期重了几百磅，配平出来的迎角偏大，看起来像气动数据有问题。排查时先把总重打印出来核对，mass/weight-lbs这个属性一读就知道对不对。

<metrics> <wingarea unit="FT2">174.0</wingarea> <wingspan unit="FT">35.8</wingspan> <chord unit="FT">5.0</chord> <htailarea unit="FT2">32.0</htailarea> <htailarm unit="FT">16.5</htailarm> <vtailarea unit="FT2">16.0</vtailarea> <vtailarm unit="FT">14.5</vtailarm> <location name="AERORP" unit="IN"><x>40.0</x><y>0</y><z>0</z></location> </metrics>

这段是整个文件里最不该出错的段落，因为它全是静态数字，一旦定下来就不该频繁改。我的习惯是给它单独写一份校验清单：面积、翼展、弦长三者之间的几何关系是否自洽，平尾力臂是否落在机身长度范围内，惯量是否满足主惯量大于次惯量的基本约束。这些粗略检查能挡掉大部分手误。

2.3 气动段与函数树，系数怎么组织才不乱

<aerodynamics>段按轴组织：LIFT、DRAG、SIDE、ROLL、PITCH、YAW。每个轴下挂若干<function>，每个 function 有唯一的名字，惯例写成aero/coefficient/CLalpha这种形式。function 内部是一棵表达式树，最常用的节点是product（连乘）、sum（求和）、table（一维或二维插值）、property（读属性）、value（常数）。

一个典型的升力项这样写：

<axis name="LIFT"> <function name="aero/coefficient/CLalpha"> <description>Lift due to alpha</description> <product> <property>aero/qbar-psf</property> <property>metrics/Sw-sqft</property> <table> <independentVar lookup="row">aero/alpha-deg</independentVar> <tableData> -10.0 -0.80 0.0 0.25 5.0 0.45 10.0 0.62 </tableData> </table> </product> </function> </axis>

这里aero/qbar-psf是动压，由速度与密度算出来；metrics/Sw-sqft是参考面积，正是前面 metrics 段定义的；table 给出迎角到升力系数的映射。三项连乘就得到升力。写法上没什么花哨，关键在于表数据的范围和斜率要符合物理直觉：线性段斜率大约在每度 0.08 到 0.11 之间，失速迎角之后系数要下降，不能一路线性延伸。表外插值的行为取决于版本，有的做线性外推，有的保持端点值，超出表范围的数据一定要谨慎。

阻力项通常拆成零升阻力和诱导阻力两部分，诱导阻力用升力系数的平方除以某个系数。俯仰力矩项要包含迎角贡献、升降舵贡献、俯仰角速度阻尼贡献。每一项单独写一个 function，命名清晰，出问题时能一条一条关掉做定位。全部塞进一个巨大表达式里，后期维护是灾难。

注意：lookup="row"这个属性在一维表里可以省略，但二维表必须写清楚行和列分别对应哪个自变量，行列顺序写反不会报错，插值结果却是错的。

2.4 动力与起落架，引用路径的隐形陷阱

<propulsion>段引用引擎和推力器文件。写法是<engine file="demo-engine">加内层<thruster file="demo-prop">，文件名不带.xml后缀，解析器自动补全并在机型同名目录下查找。燃油箱用<tank type="FUEL">定义，带位置、容量、优先级。加油量在初始化里用<fuel>或者属性赋值控制。

这里的路径问题是高频故障点。文件放在aircraft/demo/下，引用写demo-engine就能找到；如果把引擎文件放到别处，或者目录名和机型 name 不一致，就会报"找不到引擎"。有些版本会在报错时打印完整查找路径，有些只给一句笼统提示。我的排查手法是把引擎文件临时复制到机型同名目录下，如果立刻正常，问题就锁定在路径上。

<ground_reactions>段定义起落架接触点，每个 contact 需要位置、静摩擦与动摩擦系数、滚动摩擦、弹簧刚度、阻尼系数、最大转向角、刹车归属组。弹簧和阻尼的数值要与重量匹配，否则飞机停在地面就会上下弹跳或者陷进地面。经验算法是让静止压缩量落在起落架行程的 20% 到 40% 之间，用重量除以接触点数量再除以弹簧刚度估算压缩量，反推刚度值。

2.5 飞控通道与外部系统，谁在覆盖你的操纵量

<flight_control>段定义操纵通道，每个 channel 下用 summer、gain、switch、lag 这些元件把输入信号合成到最终舵面指令。命令行或脚本里设置的fcs/elevator-cmd-norm是归一化输入，经过通道里的混合和限幅之后才变成实际舵偏。如果你在命令行里给了 0.2 的升降舵输入，却发现舵面不动，八成是被通道里的 switch 或者限幅挡掉了。

<system>段引用外部系统文件，用来实现自动油门、增稳、起落架逻辑这类功能。系统文件里的计算会在每个时间步覆盖对应属性，优先级高于命令行注入。调试时如果发现--property设了值却瞬间被改回去，先查系统文件里有没有同名属性的写入。

我的一般做法是：调试阶段把 system 段先注释掉，确认基础气动和操纵链路正常，再逐个把系统加回来。这样能明确区分"模型本身的问题"和"自动化逻辑的问题"。

3. 初始条件与脚本，时间轴上的秩序

3.1 初始化段写什么、不写什么

初始化可以用独立的 XML 文件，也可以直接内嵌在脚本的<use>元素里。独立文件的根节点是<initialize name="...">，内部常见键包括高度、空速、航迹角、迎角、侧滑角、滚转角、航向角、经纬度。写法上每个键带单位：

<initialize name="cruise"> <altitude unit="FT">3500</altitude> <vc unit="KTS">110</vc> <gamma unit="DEG">0</gamma> <alpha unit="DEG">3.5</alpha> <phi unit="DEG">0</phi> <psi unit="DEG">90</psi> <lat unit="DEG">35.0</lat> <lon unit="DEG">-110.0</lon> </initialize>

注意高度和空速、航迹角、迎角之间存在几何约束，四个量不能随意组合。给定高度和空速，再给定航迹角和迎角，俯仰角就确定了；如果同时给俯仰角又给迎角，二者冲突时以哪个为准取决于解析顺序，结果不可预期。我的原则是只给必要的独立量：高度、空速、航迹角、航向，其余交给模型推导。

操纵面初值这块，不同版本对初始化段里直接写舵面键的支持程度不一致，稳妥做法是放到脚本的事件里赋值，或者用命令行属性注入，避开版本差异。

提示：初始速度用真空速还是校准空速要分清。vc是校准空速，airspeed在部分版本里指真空速。低空低速差别不大，高空高速差别能到百分之十几，直接影响初始配平。

3.2 脚本文件的结构与时序

脚本的根节点是<runscript>，内部元素按执行顺序排列。典型结构是先用<use>指定机型与初始化，然后<run>定义起止时间和步长，中间穿插<event>，末尾跟<output>。

<runscript name="cruise"> <use aircraft="demo" initialize="reset00"/> <run start="0.0" end="300.0" dt="0.0083333"/> <event name="raise_gear" persistent="false"> <condition>simulation/sim-time-sec gt 5.0</condition> <set name="gear/gear-cmd-norm" value="0.0"/> </event> <output file="cruise.csv" type="csv" rate="60"> <property caption="Time">simulation/sim-time-sec</property> <property caption="Alt_ft">position/h-sl-ft</property> <property caption="Vcas_kts">velocities/vc-kts</property> <property caption="Alpha_deg">aero/alpha-deg</property> </output> </runscript>

dt是仿真步长，默认 0.0083333 秒，对应 120Hz。rate是输出采样率，单位赫兹。end是结束时刻，单位秒。这三个数字之间的关系是新手最容易搞混的地方：dt决定计算精度和计算量，rate只决定落盘频率，两者互不影响，但rate大于1/dt时会出现重复采样行。

<event>的persistent属性控制触发一次还是持续触发。默认行为在不同版本里有差异，我的习惯是显式写persistent="false"表示只触发一次，需要持续生效的逻辑放到系统文件或者用条件持续判断。

3.3 事件条件写法与踩过的死循环

事件条件的语法是"属性路径 + 比较运算符 + 数值"，运算符用gt、ge、lt、le、eq、ne，多个条件用and、or连接。数值不带单位，按属性本身的单位解释。写simulation/sim-time-sec gt 5.0表示仿真时间超过 5 秒。

常见的坑是条件永远不成立。比如想按高度触发，写了position/h-sl-ft gt 3000，但初始高度就是 3500，条件一开始就成立，事件在第一步就触发了，看起来像"没生效"。反过来，想按时间触发却写成了simulation/sim-time-sec gt 5，而仿真在 4.9 秒就因为其他条件终止了，事件同样不会触发。

还有一种情况是事件内部又修改了条件依赖的属性，形成自我触发。比如条件判断某个开关量大于 0.5，事件里把这个开关量设成 0.0，同时persistent写成 true，那么每次条件重新成立都会再触发一次，日志里看到的就是高频抖动。排查这类问题，把事件触发时刻打印出来对照条件属性曲线，一眼就能看出是不是自激。

4. 输出配置与命令行调参

4.1 日志指令文件与列定义

输出有两种写法：脚本里内嵌<output>段，或者用独立的日志指令文件配合命令行参数。指令文件是纯文本，每行一个属性路径，#开头为注释，空行忽略。这种写法的好处是改列不用动机型文件和脚本，调试期换来换去很方便。

# demo log directives simulation/sim-time-sec position/h-sl-ft velocities/vc-kts aero/alpha-deg aero/beta-deg fcs/elevator-pos-rad fcs/throttle-cmd-norm propulsion/engine/thrust-lbs mass/weight-lbs

属性路径的正确性完全靠记忆和文档，拼错不报错。我的做法是先写一个"探针脚本"，把怀疑的路径全部列进去，跑 1 秒，看哪几列是常数 0。真正的物理量极少在 1 秒内严格为 0，恒为 0 的基本可以判定是路径错误。

注意：同一份指令文件里的属性如果分属不同子系统，某些子系统在初始化阶段尚未计算，前几行可能是 0，这不一定是路径错误。判断方法是看后面几百行是否出现非零值。

4.2 命令行参数逐条拆解

命令行是调参的主战场，常用参数整理如下：

不同构建版本对这些参数的支持略有差别，尤其是--property的分隔符，有的版本接受逗号，有的接受等号。动手之前先跑一次--help，把当前版本的参数表存一份，比记别人的笔记靠谱。

一个完整的调用示例：

jsbsim --aircraft=demo \ --scriptname=cruise.xml \ --logdirectivefile=probe.txt \ --logoutput=run01.csv \ --lograte=60 \ --property=fcs/throttle-cmd-norm,0.75 \ --property=gear/gear-cmd-norm,0.0 \ --end=300

命令行属性注入的优先级很高，通常高于初始化赋值。这意味着你可以用同一个脚本跑不同的工况，不必为每个工况写一份初始化文件。批量扫描参数时这个特性非常省事：外层写个循环，每次换一个--property的值，输出文件名带上参数编号。

4.3 用属性注入做现场调参的正确姿势

属性注入看着简单，实际有两个细节要注意。第一是单位。属性路径通常自带单位后缀，-ft、-kts、-deg、-rad、-lbs这些后缀标明该属性按什么单位解释，注入的值也必须按这个单位。给position/h-sl-ft注入 1000 就是 1000 英尺，注入 1000 想表达米就错了三倍多。第二是归一化量的范围。fcs/*-cmd-norm系列是 -1 到 1 的归一化值，注入 5.0 会被限幅，看起来像没生效。

我更推荐的做法是写一个小脚本封装命令行，把常用工况固化成几组参数：

# 工况 A：巡航段，油门 0.75，起落架收起 run_case() { jsbsim --aircraft=demo --scriptname=cruise.xml \ --logoutput="case_$1.csv" --lograte=60 \ --property=fcs/throttle-cmd-norm,"$2" \ --property=gear/gear-cmd-norm,"$3" \ --end=300 } run_case A 0.75 0.0 run_case B 0.85 0.0

这样每次改工况只动一行，输出文件名自带标识，后面批量分析时不会张冠李戴。

4.4 步长、采样率、时长三个数字怎么定

这三个数字的选取有明确的权衡。步长dt太小，计算量大，跑一条十分钟的仿真要等很久；太大，积分精度不够，高频动态被抹掉，姿态响应看起来迟钝甚至发散。经验上，dt取主导动态时间常数的十分之一以下。飞机的短周期模态周期通常在几秒量级，取 120Hz 到 200Hz 足够；如果模型里有作动器动态或者高频结构模态，步长还得再小。

采样率rate决定落盘密度。分析长周期模态或者配平趋势，10Hz 到 20Hz 就够；分析短周期响应或者控制律跟随，60Hz 以上才看得清细节。这里有个容易忽略的成本：文件体积。以 60Hz 跑 600 秒，每行 12 列，大约 36000 行，文件几兆，还能接受；如果跑到 200Hz、上千秒、几十列，文件会到几百兆，后处理读取都费劲。

时长end要和脚本里的run段配合。命令行给的end通常起到截断作用，脚本里的end定义的是计划时长。我一般把脚本里的end设得比实际需要长一点，用命令行--end精确控制，这样同一份脚本能跑不同长度的算例。

提示：rate设成比1/dt大的值时，输出的相邻行可能完全相同，做差分或者求导时会得到一堆零，误以为是数据卡住了。看到平台状的曲线先查这两个数字。

5. 从零跑通一条巡航段算例

5.1 文件落地与目录约定

假设工程根目录叫sim_workspace，结构这样组织：

sim_workspace/ ├── aircraft/ │ ├── demo.xml │ └── demo/ │ ├── demo-engine.xml │ ├── demo-prop.xml │ └── reset00.xml ├── scripts/ │ └── cruise.xml ├── logs/ │ └── probe.txt └── output/

机型文件放aircraft/下，附属文件放同名目录，脚本和日志指令文件分开放，输出统一进output/。这个结构不是强制的，但它把"模型资产"和"运行产物"分开了，清理输出不会误删模型。

5.2 三个文件的最小可用模板

机型文件的最小骨架，保留必要段落，气动只写升力和俯仰两项，够跑通验证链路：

<?xml version="1.0"?> <fdm_config name="demo" version="2.0" release="1.0"> <metrics> <wingarea unit="FT2">174.0</wingarea> <wingspan unit="FT">35.8</wingspan> <chord unit="FT">5.0</chord> <htailarea unit="FT2">32.0</htailarea> <htailarm unit="FT">16.5</htailarm> <location name="AERORP" unit="IN"><x>40.0</x><y>0</y><z>0</z></location> </metrics> <mass_balance> <emptywt unit="LBS">1600.0</emptywt> <location name="CG" unit="IN"><x>40.0</x><y>0</y><z>0</z></location> <ixx unit="SLUG*FT2">1200.0</ixx> <iyy unit="SLUG*FT2">1800.0</iyy> <izz unit="SLUG*FT2">2600.0</izz> <ixz unit="SLUG*FT2">0.0</ixz> </mass_balance> <ground_reactions> <contact type="BOGEY" name="NOSE"> <location unit="IN"><x>20.0</x><y>0</y><z>-60.0</z></location> <static_friction>0.8</static_friction> <dynamic_friction>0.5</dynamic_friction> <rolling_friction>0.02</rolling_friction> <spring_coeff unit="LBS/FT">3000.0</spring_coeff> <damping_coeff unit="LBS/FT/SEC">300.0</damping_coeff> <max_steer unit="DEG">0.0</max_steer> <brake_group>NONE</brake_group> </contact> </ground_reactions> <propulsion> <engine file="demo-engine"> <feed>0</feed> <thruster file="demo-prop"> <location unit="IN"><x>10.0</x><y>0</y><z>0</z></location> <orient unit="DEG">0.0</orient> </thruster> </engine> <tank type="FUEL"> <location unit="IN"><x>45.0</x><y>0</y><z>0</z></location> <capacity unit="LBS">300.0</capacity> </tank> </propulsion> <flight_control name="FCS"> <channel name="Pitch"> <summer name="Elevator Sum"> <input>fcs/elevator-cmd-norm</input> <clipto><min>-1.0</min><max>1.0</max></clipto> </summer> </channel> <channel name="Throttle"> <summer name="Throttle Sum"> <input>fcs/throttle-cmd-norm</input> <clipto><min>0.0</min><max>1.0</max></clipto> </summer> </channel> </flight_control> <aerodynamics> <axis name="LIFT"> <function name="aero/coefficient/CLalpha"> <product> <property>aero/qbar-psf</property> <property>metrics/Sw-sqft</property> <table> <independentVar>aero/alpha-deg</independentVar> <tableData> -5.0 -0.25 0.0 0.25 5.0 0.65 10.0 1.05 </tableData> </table> </product> </function> </axis> <axis name="PITCH"> <function name="aero/coefficient/Cmalpha"> <product> <property>aero/qbar-psf</property> <property>metrics/Sw-sqft</property> <property>metrics/cbarw-ft</property> <table> <independentVar>aero/alpha-deg</independentVar> <tableData> -5.0 0.10 0.0 0.00 5.0 -0.10 10.0 -0.20 </tableData> </table> </product> </function> </axis> </aerodynamics> </fdm_config>

脚本文件按前面的模板写，注意机型名和初始化文件名对应。日志指令文件用探针版，先只放十个属性。

5.3 执行与结果核对

第一次跑的时候，命令行加上--end=10，只跑十秒，看能不能正常结束。检查三件事：启动日志里有没有警告、CSV 的列数是否和指令文件行数一致、时间列是否从 0 递增到接近 10。

第二步把时长放到 300 秒，观察高度、空速、迎角三条曲线。一条正常的巡航段，高度应该基本持平或者缓慢变化，空速在配平点附近小幅波动，迎角稳定在几度范围内。如果高度单调下降，检查升力是否足以平衡重量；如果迎角持续增大后突然跳变，检查气动表范围是否够用；如果空速发散，检查阻力项和推力是否匹配。

配平点的估算可以手算验证。取海平面密度 0.002377 slug/ft3，空速 110 节换算成 185.6 ft/s，动压 q = 0.5 × 0.002377 × 185.6² ≈ 41 psf。总重 2400 磅时，需要的升力系数 CL = 2400 / (41 × 174) ≈ 0.337。在这个例子里的升力表，CL 从 0.25 到 0.65 对应迎角 0 到 5 度，线性插值得到迎角约 1.7 度。如果仿真的稳定迎角在 3 度以上，说明重量、面积或者密度有一项对不上，按这个顺序逐个排查。

5.4 用脚本做二次分析

CSV 拿到手，用 Python 做几步基础检查很快：

import numpy as np import pandas as pd df = pd.read_csv("output/run01.csv") df.columns = [c.strip() for c in df.columns] t = df["Time"].to_numpy() dt = np.diff(t) print("采样间隔 min/max:", dt.min(), dt.max()) print("时长:", t[-1] - t[0]) # 高度变化率，用于判断是否稳定 h = df["Alt_ft"].to_numpy() roc = np.gradient(h, t) print("高度变化率范围 ft/s:", roc.min(), roc.max()) # 配平段平均迎角 mask = t > t[0] + 0.5 * (t[-1] - t[0]) print("后半段平均迎角 deg:", df.loc[mask, "Alpha_deg"].mean())

采样间隔检查很关键。如果间隔出现周期性跳变或者为零，说明输出速率和步长的关系有问题；如果间隔稳定但比名义值大很多，说明中间有大量计算被跳过或者输出被节流。这两类问题在曲线上不一定看得出来，但会在求导、频谱分析时放大成噪声。

6. 常见问题与排查速查

6.1 静默失败类问题

静默失败是这套工具最费时间的地方，因为程序不报错，你只能怀疑自己的物理理解。典型表现和定位方法：

属性写成 0。概率最高的是路径拼写错误。做法是把所有路径集中在一个指令文件里，跑一秒，把恒为 0 的列挑出来逐个比对文档。第二种可能是该子系统在启动阶段未初始化，把时长拉长到十秒再看。

舵面指令无效。先确认飞控通道里有没有限幅或者开关把它挡掉，再看系统文件有没有覆盖同名属性。最快的验证方式是把 system 段注释掉重跑一次。

初始条件不生效。检查命令行是否给了同名属性，命令行优先级更高；再检查脚本里有没有<reset>或者事件把状态重新赋值。还有一种情况是初始化文件里的键名拼错，解析器忽略未知键，于是那个量保持默认值。

引擎推力恒为零。看引擎文件的引用路径是否正确、油门通道是否接上、油箱是否有油。油门接上了但油量为零，推力照样是零，日志里两列都得看。

6.2 数值发散类问题

发散的表现是姿态角或者速度在几秒内迅速增大到不合理范围。原因通常集中在四处：惯量与质量不匹配、气动系数符号错误、弹簧阻尼参数不当导致地面接触力剧烈震荡、步长过大。

惯量的检查方法是看俯仰角加速度对舵面的响应是否合理。给一个小的升降舵阶跃，力矩大约等于舵效系数乘动压乘面积乘力臂，除以俯仰惯量得到角加速度，数量级应该在每秒几度的平方量级。算出来的值和仿真的初始斜率差一个数量级，就是惯量填错了。

气动符号错误更隐蔽。俯仰力矩对迎角的导数应该为负（静稳定），写成正的会直接发散，但曲线前半段可能看起来还算正常，容易误判成数值问题。

地面弹跳多数是弹簧刚度和阻尼比不匹配。阻尼比按临界阻尼的 0.3 到 0.7 取，用刚度、质量反算阻尼系数，比拍脑袋填值靠谱。临界阻尼系数等于 2 乘根号下刚度乘质量，取这个值的零点几倍就合适。

6.3 排查速查表

这张表覆盖了我在实际调试中遇到的大部分情况。真正难缠的是几个原因叠加：比如路径错误导致引擎推力为零，同时重心位置填错导致配平异常，两条曲线都不对，看起来像气动模型整体崩了。这时候的办法是二分法，先把动力段注释掉，用纯滑翔状态验证气动，再逐步加回动力和系统。

我在实际使用中的体会是，这套工具的学习曲线陡峭的部分不在气动建模，而在文件之间的耦合关系。把三件套的职责边界记牢，把属性路径当成接口来管理，把每次改动都落到可对比的日志上，大部分"玄学问题"都会变成可以定位的工程问题。最后分享一个习惯：每建一个新机型，先写一个只含时间、高度、空速、迎角四个属性的探针日志，跑十秒，确认链路通了再往上加复杂度。这十秒能省掉后面几个小时的猜谜。