数据输出与解释¶
SHARPy 的原始输出格式为 HDF5 和 VTK。工程实践任务通常还需要一层抽取与标准化，以下仅为参考，你可以根据你的实际情况自行定义结构化的输出。
为什么需要标准化输出¶
SHARPy 的原生输出直接来自求解器内部数据结构，存在以下问题：
- 字段命名不稳定：不同求解器版本的输出键名可能变化。
- 坐标系不透明：原始输出不携带坐标轴、符号和单位元数据。
- 多工况对比困难：每个算例的原始输出分散在不同目录中，缺乏统一索引。
因此，可以在 SHARPy 原始输出之上构建标准化数据集层，包含索引文件、元数据文件和按约定格式导出的 CSV/JSON 数据。
标准化输出目录结构¶
以下为推荐的输出目录结构：
outputs/<experiment_name>/
├── manifest.json # 全局清单
├── summary.json # 汇总统计
├── README.md # 实验说明
├── plots/ # 快速诊断图
│ ├── peak_tip_uz_by_matrix.png
│ └── peak_lift_by_matrix.png
├── sharpy_runs/
│ └── <case_id>/ # 每个独立算例
│ ├── raw_results.json # 从 SHARPy HDF5 提取的结构化 JSON
│ ├── wake_coordinates.json # 尾迹几何坐标
│ ├── sharpy_stdout.log # SHARPy 标准输出
│ ├── csv/
│ │ ├── time_series.csv # 时间序列数据
│ │ ├── tip_load.csv # 翼尖载荷
│ │ ├── root_resultants.csv # 根部反力/内力/外力
│ │ ├── nodes.csv # 节点位移与转角
│ │ ├── distributed_strain.csv # 分布应变
│ │ └── spanwise_aero_forces.csv # 展向气动力分布
│ └── beam/ # SHARPy VTK 梁输出
│ └── aero/ # SHARPy VTK 气动输出
└── standardized_dataset/ # 统一数据集视图
├── metadata/
│ ├── case_index.json # 全部 case_id 索引
│ ├── case_index.csv
│ └── dataset_metadata.json # 数据集模式与版本
├── structure_cases/
├── load_cases/
├── responses/
├── figures/
└── quality/
主要数据文件说明¶
manifest.json¶
全局清单文件，逐 case 记录：
case_id：唯一标识。status：completed、failed。output_dir：算例输出目录。csv_paths：各 CSV 文件路径。raw_result_path：原始结果 JSON 路径。log_paths：stdout / stderr 日志路径。error：失败原因（如有）。
raw_results.json¶
从 SHARPy HDF5 提取的结构化数据，是后续所有 CSV 和 analysis 的源。顶层结构：
{
"case": "alpha_5_deg_U25",
"alpha_deg": 5.0,
"velocity_m_per_s": 25.0,
"time_history": [ ... ],
"peak_response": {
"tip": { "displacement_m": [ux, uy, uz], "rotation_rad": [rx, ry, rz] },
"total_aero_force_N": [Fx, Fy, Fz],
"total_lift_N": <scalar>
},
"units": { "displacement": "m", "rotation": "rad", "force": "N", ... },
"conventions": { ... }
}
time_series.csv¶
每个采样点一行，常用列如下：
| 列 | 含义 | 单位 |
|---|---|---|
time_s |
时间 | s |
frequency_hz |
激励频率 | Hz |
applied_load_raw_N |
原始外加载荷 | N 或 N·m |
tip_ux_m, tip_uy_m, tip_uz_m |
翼尖位移三分量 | m |
tip_rx_rad, tip_ry_rad, tip_rz_rad |
翼尖转角三分量 | rad |
total_aero_force_x_N, total_aero_force_y_N, total_aero_force_z_N |
总气动力分量 | N |
total_lift_N |
总升力 | N |
nodes.csv¶
每个采样点的全节点位移/转角，列结构：
| 列 | 含义 |
|---|---|
time_s, case_id, frequency_hz |
元数据 |
node |
节点编号 |
y_m |
节点展向坐标 |
ux_m, uy_m, uz_m |
节点位移三分量 |
rx_rad, ry_rad, rz_rad |
节点转角三分量 |
distributed_strain.csv¶
每个采样点的全单元应变/曲率/内力，列结构：
| 列 | 含义 | 单位 |
|---|---|---|
element_index |
单元编号 | — |
epsilon_x |
轴向应变 | 无量纲 |
gamma_y, gamma_z |
剪切应变 | 无量纲 |
kappa_x_1_per_m |
扭转曲率 | m⁻¹ |
kappa_y_1_per_m, kappa_z_1_per_m |
弯曲曲率 | m⁻¹ |
internal_Fx–internal_Mz |
截面内力 | N / N·m |
root_resultants.csv¶
每个采样点的根部合力/合矩，列结构：
| 列 | 含义 |
|---|---|
quantity |
root_external_resultant / root_internal_resultant / root_reaction |
Fx–Mz |
对应的力/力矩分量 |
spanwise_aero_forces.csv¶
展向气动力分布，每个翼展站位的气动力分量和合升力。
字段命名原则¶
本项目的标准化命名遵循以下约定：
- 物理量和单位写在同一个列名中：
tip_uz_m（翼尖 z 位移，米）、frequency_hz（频率，赫兹）。 - 列名用下划线分隔：
total_lift_N、epsilon_x、kappa_z_1_per_m。 - 力分量使用
Fx/Fy/Fz，力矩分量使用Mx/My/Mz。 - 转角使用
rx/ry/rz，单位为弧度。 - 元数据列包括
case_id、time_s、frequency_hz、alpha_deg、velocity_m_per_s等。
schema_version 与版本管理¶
每个标准化 JSON 文件都携带以下元数据：
{
"schema_version": "1.0.0",
"generated_at_utc": "2026-06-15T00:00:00Z",
"units": { ... },
"coordinates": { ... },
"conventions": { ... }
}
下游代码应从 case_index.json 入口开始，而不是硬编码算例目录路径。
数据质量检查¶
本项目的数据质量检查（QC）覆盖以下方面：
- 结构刚度检查：刚度数据库行是否对称正定。
- 载荷覆盖率：是否覆盖全部三类结构 case × 全部载荷方向 × 全部载荷形式。
- 根部平衡：静态工况下 \(\text{root\_reaction} + \text{root\_external\_resultant} \approx 0\)。
- 响应有界性：位移和转角是否在物理合理范围内（阈值 10 m / 10 rad）。
- 动态非零信号检测：动态全状态快照是否包含非零振动信号。
- 图像有效性：生成的 PNG 图片是否可正常读取。
QC 报告写入 quality/quality_report.json（机器可读）和 quality/quality_report.md（可读格式）。
实操建议¶
- 下游分析代码应通过
case_index.json遍历算例，而不是硬编码目录。 - 读取响应文件前，先读取其中的
units、coordinates、conventions元数据块。 - 纯结构算例和耦合算例的坐标轴可能对换（梁轴 \(x\) ↔ 翼展 \(y\)），对比前要先确认方向一致。
- 原始 VTK 和 HDF5 文件体积较大，建议使用 DVC 等外部存储管理，Git 只保存指针文件。