# 建筑结构课程评测代码总览 (Course Evaluation Toolkit)

## 项目简介
本项目面向建筑结构振动课程评测场景，提供三类核心功能：

1. 根据基底简谐激励频率，预测模型顶部加速度 Z 向响应的整体均方根 RMS 值。
2. 根据顶部自由衰减响应，识别结构一阶自振频率和阻尼比。
3. 根据顶部强迫振动响应，反推出输入简谐波的激振频率。

项目包含三套脚本目录：`scripts`、`scripts_2`、`scripts_3`。三套脚本分别对应 RMS 预测、结构动力特性识别、激振频率逆向预测。

## 课程评测流程
教师评测时可按以下流程使用代码：

1. **顶部响应 RMS 预测**
   教师进行一组基底激励输入试验。对每组简谐波频率，使用 `scripts` 目录下的脚本预测顶部加速度 Z 向响应的整体 RMS 值。
2. **结构动力参数识别**
   教师对模型略微做出改动后，采集顶部自由衰减响应，使用 `scripts_2` 目录下的脚本识别一阶自振频率和阻尼比。
3. **激振频率逆向预测**
   教师再次进行一组基底激励输入试验，使用 `scripts_3` 目录下的脚本，根据顶部加速度响应反推输入简谐波的激振频率。

## 项目结构

```text
Building-main/
├── downloads/                # 数据目录
│   └── Non_TMD/
│       ├── free_vib/         # 自由衰减数据
│       ├── train/            # 简谐波训练数据
│       ├── val/              # 简谐波验证数据
│       └── test/             # 其他测试数据
├── scripts/                  # 任务 1：顶部响应 RMS 预测
├── scripts_2/                # 任务 2：自振频率与阻尼比识别
├── scripts_3/                # 任务 3：激振频率逆向预测
├── requirement.txt           # Python 依赖清单
└── README.md                 # 总说明文档
```

## 三套脚本说明

### `scripts`
该目录用于完成顶部响应 RMS 预测任务。

- 输入为基底传感器信号与文件频率标签。
- 输出为顶部加速度 Z 向响应的整体 RMS 预测值。
- 主要脚本包括 `train_final.py`、`evaluate.py`、`predict_single.py`。

### `scripts_2`
该目录用于完成结构动力特性识别任务。

- 数据来源为 `downloads/Non_TMD/free_vib/` 目录下的自由衰减 CSV 文件。
- 使用顶部响应传感器 `WSMS00007` 的 `value3` 列。
- 输出一阶自振频率、阻尼比与诊断图像。

### `scripts_3`
该目录用于完成激振频率逆向预测任务。

- 使用强迫振动数据，如 `downloads/Non_TMD/val/` 或 `downloads/Non_TMD/test/`。
- 使用顶部响应传感器 `WSMS00007` 的 `value3` 列识别主频。
- 主要脚本为 `task4_predict_freq.py`。

## 传感器约束

- **顶部响应传感器**
  任务 2 和任务 3 统一使用 `WSMS00007` 的 `value3` 列。
- **基底输入传感器**
  `WSMS00012` 的 `value1` 列用于参考与对照。
- **任务 3 频率逆推**
  激振频率预测直接基于顶部响应频谱结果。

## 环境准备

项目建议使用 **Python 3.10** 创建新的虚拟环境，再安装根目录的 `requirement.txt`。

**1. 创建虚拟环境**

```bash
py -3.10 -m venv .venv
```

**2. 激活虚拟环境**

```bash
.\.venv\Scripts\activate
```

**3. 安装依赖**

```bash
python -m pip install -r requirement.txt
```

`requirement.txt` 已包含三套脚本使用到的核心依赖：

- `numpy`
- `pandas`
- `scipy`
- `matplotlib`
- `scikit-learn`

## 使用方法

### 1. 顶部响应 RMS 预测
对单个简谐波文件预测顶部响应 RMS：

```bash
python scripts\predict_single.py --file downloads\Non_TMD\val\harmonic_5mm_0.75Hz.csv
```

对全量样本进行评估：

```bash
python scripts\evaluate.py
```

如需重新训练模型：

```bash
python scripts\train_final.py
```

### 2. 自由衰减法识别自振频率和阻尼比
对自由衰减文件执行识别：

```bash
python scripts_2\task3_identify.py --file downloads\Non_TMD\free_vib\free_decay.csv
```

脚本输出内容包括：

- 一阶自振频率 `f_n`
- 对数衰减率 `delta`
- 阻尼比 `zeta`
- 原始波形、滤波结果与包络线图像

### 3. 根据顶部响应反推激振频率
对单个强迫振动文件执行频率逆推：

```bash
python scripts_3\task4_predict_freq.py --file downloads\Non_TMD\val\harmonic_5mm_0.75Hz.csv
```

脚本输出内容包括：

- 稳态段采样范围
- 预测激振频率
- 文件名中的频率真值
- 绝对误差
- 时域与频域诊断图像

## 结果输出

运行脚本后，图像与评测结果默认保存到 `evaluation_outputs/` 目录下，对应子目录如下：

- `evaluation_outputs/task1_final/`
- `evaluation_outputs/task3_identify/`
- `evaluation_outputs/task4_predict_freq/`

## 说明

- `scripts` 目录负责 RMS 预测。
- `scripts_2` 目录负责自由衰减识别。
- `scripts_3` 目录负责激振频率逆推。
- 数据文件命名中包含频率标签时，脚本会自动提取真值用于误差统计。