FCC-Dynamics-C

Appearance

Configuration Input System & Multidimensional Interpolation ​

> Status: PATCH · 已对齐 PCR Master Blueprint v1.0 > 范畴: io/reader/、data/input/、io/interp/InterpTableND.h > 依赖: types、monad

Overview ​

The simulation has transitioned from legacy, fragmented text formats (.dat, fig_XXXX.TXT) to a modern, structured configuration suite. This system leverages YAML for hierarchical metadata and multidimensional (ND) interpolation tables, and CSV for high-density 1-dimensional profiles.

> 架构约束：配置文件严格分为 Plant-Controller-Runner (PCR) 三个域。Plant（rocket_v1/、world/）= 真值物理资产；Controller（fcc_v1/）= 飞控软件；Runner（sim/）= 部署执行上下文。详见 07_Runtime/PCR_Configuration.md 与 07_Runtime/PlantScope.md。装配流程见 07_Runtime/Assembler_and_Runner.md。

Core Design Principles ​

1. Unified Configuration Pipeline ​

  • Metadata First: YAML is used as the primary entry point (env.yaml, aero.yaml, engine.yaml). It defines the structure, file references, and global constants.
  • External Data References: Large datasets (like atmospheric profiles) are stored in CSVs and referenced by name in the YAML configuration.
  • Type Safety: The system uses Time, Angle, and Distance wrappers rather than raw doubles to prevent unit mismatch errors during data ingestion.

2. Multidimensional Interpolation (Shared Grid Design) ​

To handle complex physics like Aerodynamic Coefficients (which depend on Mach, Alpha, and Beta), we use a "Shared Grid" YAML format.

Design Motivation ​

  • Consistency: Ensuring multiple tables (e.g., $C_x, C_y, C_z$) use the exact same break-points for Mach and Alpha.
  • Redundancy Reduction: Storing the grid once per file instead of repeating it for every coefficient.
  • Human-Readable Structure: Nesting data under specific physical keys (e.g., ascending, descending) for easier debugging.

YAML Structure Example ​

yaml
grid:
    dim1: [0.0, 0.5, 1.0, 2.0] # Mach
    dim2: [0.0, 5.0, 10.0]     # Alpha (deg)
tables:
    cx:
        data: [ ... ] # Flattened array of size (dim1 * dim2)
    cy:
        data: [ ... ]

3. Extrapolation & Periodicity ​

  • Clamping with Warnings: If a query falls outside the defined grid, the system clamps to the nearest boundary and issues a non-fatal warning (throttled to prevent log flooding).
  • Periodic Boundaries: For variables like Azimuth ($0-360^\circ$), the system automatically wraps coordinates before interpolation.

Technical Summary: InterpTableND ​

1. Internal Implementation ​

The InterpTableND class manages an $N$-dimensional hypercube of data.

  • Data Storage: A flat std::vector<double> representing the $N$-dimensional array.
  • Indexing: Map $N$ coordinates $(x_1, x_2, \dots, x_n)$ to a flat index using strides: $Index = \sum (i_k \times \text{stride}_k)$.
  • Interpolation Algorithm: Recursive linear interpolation (Lerp). For $N$ dimensions, it performs $2^N - 1$ linear interpolations.

2. Usage Pattern (C++) ​

Interpolators are loaded once at装配期 by runtime::Assembler and stored directly as flat data inside env::Atmosphere/AeroTable/... (详见 02_Physical_World/Environment_Fields.md 与 02_Physical_World/Plant_Model_Assets.md)。禁止 std::function 闭包持有大表（违反 Blueprint §7.7 严格只读 + 指针稳定要求）。

cpp
// 1. 装配期：Assembler 解析 YAML
auto table = yaml_reader.load_table_nd("aero/ascending.yaml", "cx");

// 2. 把数据 move 进强类型 owner
plant::model::AeroTable aero;
aero.cx = std::move(table);   // 大表平铺 vector，无 lambda 闭包

// 3. 运行期：probe_aero 直接调用 owner 方法
double cx = aero.cx.interpolate({mach, alpha});

> v0 → v1 修正：v0 大量使用 std::function<double(double, double)> 装大气/气动；v1 全部换成强类型对象 + 平铺数据。原因：函数对象禁阻 C-distillation、不可序列化、堆分配难以追踪。

3. Data Migration Workflow ​

We use Python automation to bridge the gap between legacy text exports and the new YAML/CSV format.

  • reliable_converter.py: Parses legacy fixed-width or space-delimited multidimensional tables, verifies the product of grid dimensions against the data count, and exports structured YAML.
  • csv_converter.py: Converts 1D atmospheric or engine data into clean CSV headers.

Critical Lessons Learned ​

  • Memory Safety: Never capture InterpTableND by reference in lambdas if the table is local to an initialization function. Always move into a strong-typed owner（如 env::Atmosphere、plant::model::AeroTable），不要用 lambda 闭包。
  • 指针稳定性: 装配期 WorldEnv.plant_assets.* vector 必须 reserve(N)，之后只 emplace_back，不超容量。RocketBody 持有的 spec 指针生命周期与 WorldEnv 一致（Blueprint §7.7）。
  • Standard Compliance: Large YAML files (10,000+ points) require manual line-breaking in the "inline list" format to remain compatible with standard string parsers and version control diffs.
  • Scaling: For tables with more than 3 dimensions, consider pre-calculating strides and using a non-recursive interpolation approach to maintain performance.

Reference ​

  • Blueprint §7.7（WorldEnv 严格只读 + 装配期 path_index RAII）、§7.15（Environment / Plant 分离）
  • 07_Runtime/PCR_Configuration.md — PCR YAML 目录结构
  • 07_Runtime/Assembler_and_Runner.md — 装配流水线
  • 07_Runtime/PlantScope.md — 部署切片
  • 02_Physical_World/Environment_Fields.md — env::Atmosphere/GravityField/WindField 类型
  • 02_Physical_World/Plant_Model_Assets.md — plant::model::*Spec 类型