FCC-Dynamics-C

Appearance

Plant Model Assets ​

> Aligned with PCR Master Blueprint v1.0 — see Blueprint §2.4. > 职责：定义"对象专属的本构关系"——一台具体火箭的所有规格表（推力曲线、气动表、质量分布、设备规格）。是 YAML 驱动的不可变数据。 > C-Distillation note：所有 *Spec 结构都是 POD（含 InterpTable*）。蒸馏阶段，InterpTable 转为定长 C 数组 + 静态插值函数。

1. 资产 vs 场 vs 物理函数 ​

为避免混淆，先明确三者职责：

层内容数学形式谁来"做计算"
environment/普适场f(x, t)自己（pressure_at 等）
plant/model/（本文档）对象规格表静态数据 + 插值函数数据为主，提供 lookup
plant/physics/力学函数compute_*(BodyEnv, RocketBody) → Forces自己（读 model 表 + 计算）
plant/hardware/机械面状态演化step_*(Mech, cmd, dt)自己（ODE-like 单步）

plant/model/ 是数据，plant/physics/ 是算法。两者分离让"换火箭型号只改 YAML"成为可能。

2. 资产分类总览 ​

plant::model 命名空间下定义所有规格类型：

mermaid
graph TB
    BA[BodyAsset<br/>整体描述] --> ES[EngineSpec]
    BA --> SS[ServoSpec]
    BA --> FS[FinSpec]
    BA --> IS[ImuSpec]
    BA --> GS[GpsSpec]
    BA --> ICS[IcuSpec]
    BA --> MS[MassPropsSpec]
    BA --> AS[AeroSpec]
    BA --> InstallParams

sim::WorldEnv 按 type_id 索引存储各类 spec 的 std::vector，RocketBody 内每个 device 持有 const *Spec 指针。

3. 推进系统资产 ​

3.1 EngineSpec：发动机规格表 ​

cpp
// src/plant/model/EngineSpec.h
namespace plant::model {

struct EngineSpec {
    // ── 性能曲线 ──
    InterpTable1D thrust_curve;        // 真空推力(t_burn) → N
    InterpTable1D mass_flow_curve;     // 总质量流(t_burn) → kg/s
    InterpTable1D mixture_ratio_curve; // 氧化剂/燃料比(t_burn)

    // ── 几何 ──
    double nozzle_exit_area;           // Sa（背压补偿用），单位 m^2
    Vec3_T<frame::BODY> install_pos;   // 安装位置（相对火箭基准点）
    Quat_T<frame::BODY, frame::BODY> install_rot;  // 喷管对准方向

    // ── 摄动修正 ──
    std::array<double, 12> perturb_coeffs;     // 推力摄动 12 系数
    std::array<double, 4>  stage_deviations;   // 各阶段偏差

    // ── 时序参数 ──
    Time start_duration;               // OFF→RUNNING 启动用时
    Time shutdown_duration;            // 关机过渡用时
};

} // namespace plant::model

3.2 ServoSpec / FinSpec ​

cpp
struct ServoSpec {
    double max_rate_deg_s;       // 最大角速度
    double max_torque;           // 最大力矩
    Angle  range_min, range_max; // 行程限位
    double time_constant;        // 一阶响应时间常数
};

struct FinSpec {
    InterpTable3D cl_table;      // 升力系数(Mach, alpha, deflection)
    InterpTable3D cd_table;      // 阻力系数(同上)
    InterpTable3D cm_table;      // 力矩系数(同上)
    Vec3_T<frame::BODY> pivot_pos;
    double reference_area;
    double reference_length;
};

4. 气动资产 ​

4.1 AeroSpec：气动力查表 ​

cpp
struct AeroSpec {
    InterpTable3D drag_table;    // Cd(Mach, alpha, beta)
    InterpTable3D lift_table;    // CL(Mach, alpha, beta)
    InterpTable3D side_table;    // CY(Mach, alpha, beta)
    InterpTable3D moment_table;  // Cm(Mach, alpha, beta)
    InterpTable3D yaw_table;     // Cn
    InterpTable3D roll_table;    // Cl

    double reference_area;       // S_ref
    double reference_length;     // L_ref（用于力矩系数无量纲化）
    Vec3_T<frame::BODY> aero_center;  // 气动参考点
};

坐标系：所有力系数在 AERO frame 定义，plant::physics::compute_drag 内部完成 AERO → BODY 旋转。

4.2 MassPropsSpec：质量分布 ​

cpp
struct MassPropsSpec {
    // 质量随燃烧时间变化
    InterpTable1D mass_curve;        // m(t_burn) → kg
    InterpTable1D centroid_x_curve;  // x_cg(t_burn) → m
    InterpTable1D centroid_y_curve;
    InterpTable1D centroid_z_curve;

    // 惯量张量（对角元 + 主交叉项）
    InterpTable1D Ixx_curve, Iyy_curve, Izz_curve;
    InterpTable1D Ixy_curve, Ixz_curve, Iyz_curve;

    double dry_mass;             // 空壳干质量
    Vec3_T<frame::BODY> dry_centroid;
};

5. 航电资产 ​

5.1 传感器规格 ​

cpp
struct ImuSpec {
    Time   period;                   // 采样周期（典型 1ms）
    double accel_noise_sigma;        // 加速度白噪声 std
    double accel_bias_stability;     // Allan variance 中频
    double gyro_noise_sigma;
    double gyro_bias_stability;
    double quantization_lsb_v;       // 速度增量量化粒度
    double quantization_lsb_theta;   // 角度增量量化粒度
};

struct GpsSpec {
    Time   period;                   // 典型 100ms
    double pos_noise_sigma_m;        // 位置噪声 std（ECF 三轴）
    double vel_noise_sigma_m_s;
    Time   latency;                  // 端到端延迟
    uint8_t default_fix_quality;
};

5.2 控制设备规格 ​

cpp
struct IcuSpec {
    // 时序控制单元参数（事件触发、看门狗等）
    Time watchdog_timeout;
    uint16_t max_pending_events;
};

ECU、SCU、FinCtrl 的规格表通常嵌在 EngineSpec / ServoSpec / FinSpec 内部，因为它们的电子参数与机械参数强耦合，无独立 EcuSpec。

6. 整体装配：BodyAsset & InstallParams ​

cpp
// 描述"一台火箭"的索引集合
struct BodyAsset {
    uint32_t  body_type_id;
    std::string  name;

    // 通过 type_id 引用 WorldEnv 中的 spec vectors
    std::vector<EngineId>  engine_ids;
    std::vector<ServoId>   servo_ids;
    std::vector<FinId>     fin_ids;
    std::vector<ImuId>     imu_ids;
    std::vector<GpsId>     gps_ids;
    std::vector<IcuId>     icu_ids;

    uint32_t  aero_spec_id;
    uint32_t  mass_props_spec_id;
};

// 设备级安装参数（同一种 EngineSpec 可以多次安装在不同位置）
struct InstallParams {
    Vec3_T<frame::BODY> position;
    Quat_T<frame::BODY, frame::BODY> orientation;
    uint32_t  redundancy_group;     // 冗余编组
};

> 关键设计：Spec 是型号（一份），Install 是安装（多份）。例如一台火箭有 4 台同型号 RD-180，engine_specs 里只存一份 EngineSpec，RocketBody.engines[i].install 各存自己的安装位姿。

7. WorldEnv 中的存储布局 ​

cpp
// 在 simulation/env/WorldEnv.h 中
struct WorldEnv {
    // ...
    std::vector<plant::model::BodyAsset>     body_assets;
    std::vector<plant::model::EngineSpec>    engine_specs;
    std::vector<plant::model::ServoSpec>     servo_specs;
    std::vector<plant::model::FinSpec>       fin_specs;
    std::vector<plant::model::ImuSpec>       imu_specs;
    std::vector<plant::model::GpsSpec>       gps_specs;
    std::vector<plant::model::IcuSpec>       icu_specs;
    std::vector<plant::model::AeroSpec>      aero_specs;
    std::vector<plant::model::MassPropsSpec> mass_props_specs;
};

RocketBody.engines[i].spec 是 const EngineSpec*，指向 engine_specs[type_id]。访问 O(1)，无 hash。

8. YAML 加载约定 ​

yaml
# data/input/rocket_v1/engines.yaml
engines:
  - id: e_rd180
    thrust_curve_csv: rocket_v1/engine/rd180_thrust.csv
    mass_flow_csv:    rocket_v1/engine/rd180_mflow.csv
    nozzle_exit_area_m2: 0.42
    perturb_coeffs: [0.01, 0.02, ...]   # 12 个
    start_duration_s: 3.0
    shutdown_duration_s: 1.0

# data/input/rocket_v1/aero.yaml
aero:
  drag_table_csv: rocket_v1/aero/cd_table.csv
  lift_table_csv: rocket_v1/aero/cl_table.csv
  reference_area_m2: 7.07
  reference_length_m: 3.0

# data/input/rocket_v1/devices.yaml
body_assets:
  - body_type_id: 1
    name: stage_1
    engines:    [e_rd180, e_rd180, e_rd180, e_rd180]
    install:
      - position: [0.0, 0.0, -10.0]
        orientation: [...]
      # ...

加载顺序由 runtime::Assembler::load_plant_assets_() 控制。详见 07_Runtime/PCR_Configuration.md。

9. 反模式 ​

反模式为什么不行
在 EngineSpec 里持有 double current_thrustSpec 是型号定义，不持有运行时状态。运行时状态属 RocketBody.engines[i].mech
EngineSpec::compute_thrust(...) 成员方法计算属 plant/physics/，Spec 只是数据
在 plant/model/ 里 include environment/Atmosphere.hmodel 是纯数据，不依赖场
把 launch point 放在 BodyAsset 里launch point 属 frame::FrameConfig，不是火箭资产
用字符串 ID 在运行时查表字符串只在 YAML 加载期使用，运行时一律 uint32_t 下标
同型号引擎复制 EngineSpec 多份浪费内存；多份引擎共享 const EngineSpec*

10. Cross References ​

  • 力学计算如何消费这些表 → 02_Physical_World/Plant_Physics_Constitutive.md
  • 机械面如何演化 → 02_Physical_World/Plant_Hardware_Mech.md
  • 设备如何引用 spec → 03_Avionics_and_Bus/Device_Dual_Face.md
  • WorldEnv 装配 → 06_Simulation/WorldEnv_Assembly.md
  • YAML 路径协议 → 07_Runtime/PCR_Configuration.md