Building/scripts/README.md

# 建筑结构简谐激励响应预测 (Harmonic Response Prediction)

## 项目简介
本项目旨在通过数据驱动的方法，预测建筑结构在简谐波底座激振下的顶层加速度响应。工程利用机器学习算法提取核心物理特征，建立激励与响应之间的传递关系，实现对目标结构响应均方根（RMS）的快速、准确预测。

## 技术路线
本项目的核心技术链路包含数据预处理、特征工程、传递率建模与算法回归四个关键环节，逻辑清晰，具备较强的工程可解释性：

1. **稳态信号截取**
   由于原始振动数据包含起振与衰减的瞬态过程，系统通过滑动窗口结合变异系数评估，自动截取最平稳的中间段数据，消除非稳态噪声对分析的干扰。
2. **物理特征工程**
   系统从底座激励信号中提取 4 维极具代表性的物理特征作为模型输入：
   - 频率 ($f$)
   - 频率的平方 ($f^2$)
   - 激励均方根 ($x_{rms}$)
   - 理论加速度幅值 ($(2\pi f)^2 \cdot A$)
3. **传递率 (TR) 目标建模**
   模型将预测目标设定为系统的**传递率 (Transmissibility, TR)**，即输出响应与输入激励的均方根比值 ($TR = y_{rms} / x_{rms}$)。
   在最终推理阶段，通过公式 $\text{预测响应 } y_{rms} = \text{预测 } TR \times \text{实际输入 } x_{rms}$ 还原最终结果，这种无量纲化的处理极大提升了模型的泛化能力。
4. **距离权重 KNN 回归**
   采用数据标准化 (StandardScaler) 结合距离加权的 K 近邻回归 (KNeighborsRegressor) 算法。通过特征空间中的距离衰减机制，对高维空间中的传递率进行平滑拟合。

## 核心模块说明

- **`config.py`**
  全局配置中心。集中管理数据路径、传感器编号（基座输入与顶层输出）、信号截取比例以及模型超参数。
- **`dataset.py`**
  数据处理引擎。负责读取原始 CSV 振动数据、缺失值插值对齐、稳态窗口搜索、傅里叶主频计算以及核心物理特征的打包提取。
- **`train_final.py`**
  模型训练入口。读取全量简谐波数据，构建特征矩阵与目标向量完成 KNN 模型训练，将最优模型序列化保存，并输出全量数据的拟合评估曲线。
- **`evaluate.py`**
  批量评估工具。加载已保存的模型权重，对全集数据进行预测评估，生成包含理论拟合曲线、散点对比与误差分布的可视化图表。
- **`predict_single.py`**
  单样本预测脚本。支持输入特定的单一 CSV 数据文件，提供端到端的预测功能，并绘制包含时域对比、频域谱线及预测 RMS 对比的综合诊断图。

## 使用指南

**1. 训练模型**
读取配置文件中指定的数据集，执行全量训练并保存模型权重：
```bash
python scripts/train_final.py
```

**2. 批量评估**
加载已训练的模型，对样本进行批量评估与统计分析：
```bash
python scripts/evaluate.py
```

**3. 单文件预测**
对特定的单一样本进行独立预测，并生成详细的图表报告：
```bash
python scripts/predict_single.py --file path/to/your/harmonic.csv
```