# Deeplearning 使用说明

## 1. Conda 环境迁移

环境文件在 `conda_env/`：

- `conda_env/environment.portable.yml`：通用迁移（推荐）
- `conda_env/environment.lock.txt`：精确锁定（同系统/同架构优先）
- `conda_env/env.yml`：历史文件

### 1.1 创建环境

```bash
# 方式1（推荐）：通用创建
conda env create -f conda_env/environment.portable.yml
conda activate Deeplearning

# 方式2：精确复现
conda create -n Deeplearning --file conda_env/environment.lock.txt
conda activate Deeplearning

# 验证
python -V
python -c "import torch; print(torch.__version__)"
```

### 1.2 同名环境已存在时

```bash
# 方式A：保留旧环境，改名创建
conda env create -f conda_env/environment.portable.yml -n Deeplearning_v2
conda activate Deeplearning_v2

# 或者（lock 方式）
conda create -n Deeplearning_v2 --file conda_env/environment.lock.txt
conda activate Deeplearning_v2
```

```bash
# 方式B：删除旧环境后重建（谨慎）
conda env remove -n Deeplearning
conda env create -f conda_env/environment.portable.yml
conda activate Deeplearning
```

### 1.3 重新导出环境

```bash
conda env export -n Deeplearning --no-builds > conda_env/environment.portable.yml
conda list -n Deeplearning --explicit > conda_env/environment.lock.txt
```

### 1.4 主要依赖包

训练与数据处理核心依赖：

- Python 3.12
- pytorch / torchvision / torchaudio
- pandas / numpy / scipy
- scikit-learn
- matplotlib / seaborn
- openpyxl / xlrd（用于 xls/xlsx 读写）

说明：项目仓库已提供完整环境文件，优先用 `conda_env/environment.portable.yml` 或 `conda_env/environment.lock.txt` 创建环境。

### 1.5 依赖安装方式（Conda / pip）

方式 A（推荐，Conda 一步到位）：

```bash
conda env create -f conda_env/environment.portable.yml
conda activate Deeplearning
```

方式 B（Conda 最小安装，适合自定义环境）：

```bash
conda create -n Deeplearning python=3.12 -y
conda activate Deeplearning

# GPU 机器（CUDA 12.4）
conda install -y pytorch torchvision torchaudio pytorch-cuda=12.4 -c pytorch -c nvidia

# CPU 机器（无 CUDA）
# conda install -y pytorch torchvision torchaudio cpuonly -c pytorch

conda install -y pandas numpy scipy scikit-learn matplotlib seaborn openpyxl xlrd
```

方式 C（pip 安装，适合已有虚拟环境）：

```bash
pip install torch torchvision torchaudio
pip install pandas numpy scipy scikit-learn matplotlib seaborn openpyxl xlrd
```

可选开发工具：

```bash
pip install black autopep8 basedpyright
```

## 2. 项目约定

### 2.1 输入数据格式
每一类数据支持 `xls/xlsx/csv`。读取时默认取偶数列（索引 1,3,5...）作为特征，奇数列内容可忽略。

示意：

| 任意值 | 特征值 | 任意值 | 特征值 |
|---|---|---|---|
| arbitrary value | value | arbitrary value | value |

### 2.2 目录约定
训练数据放在 `Static/`，输出结果放在 `Result/`。

推荐目录：

```text
.
├─ Static/
│  └─ 20241009MaterialDiv/
└─ Result/
```

## 3. 快速开始

### 3.1 准备数据
1. 将数据目录命名为 `日期+项目名`，例如 `20241009MaterialDiv`。
2. 准备 `label_names`（建议英文或数字）。
3. 将数据目录放入 `Static/`。

### 3.2 数据目录模板

单文件模式（每个标签一个文件）：

```text
Static/
  20241009MaterialDiv/
    Acrlic.xlsx
    Ecoflex.xlsx
    PDMS.xlsx
    PLA.xlsx
    Wood.xlsx
```

多子特征模式（每个标签一个子目录，目录下可有多个文件）：

```text
Static/
  20241009MaterialDiv/
    Acrlic/
      sample_01.xlsx
      sample_02.xlsx
    Ecoflex/
      sample_01.xlsx
      sample_02.xlsx
    PDMS/
      sample_01.xlsx
      sample_02.xlsx
    PLA/
      sample_01.xlsx
      sample_02.xlsx
    Wood/
      sample_01.xlsx
      sample_02.xlsx
```

命名规则（重要）：

- `label_names` 中每一项必须与文件名（单文件模式）或子文件夹名（多子特征模式）一致。
- `label_names` 顺序就是标签编码顺序，训练结果和混淆矩阵按该顺序展示。

示例：

```python
label_names = ['Acrlic', 'Ecoflex', 'PDMS', 'PLA', 'Wood']
```

对应关系：

```text
Acrlic  <-> Acrlic.xlsx   或  Acrlic/
Ecoflex <-> Ecoflex.xlsx  或  Ecoflex/
PDMS    <-> PDMS.xlsx     或  PDMS/
PLA     <-> PLA.xlsx      或  PLA/
Wood    <-> Wood.xlsx     或  Wood/
```

### 3.3 通用：数据导入

```python
from Qfunctions.loadData import load_data

projet_name = '20241009MaterialDiv'
label_names = ['Acrlic', 'Ecoflex', 'PDMS', 'PLA', 'Wood']

# 自动识别数据模式（支持 xls/xlsx/csv）
data = load_data(projet_name, label_names)
```

### 3.4 模型调用

#### 3.4.1 MLP

```python
from Qtorch.Models.Qmlp import Qmlp

model = Qmlp(
  data=data,
  labels=label_names,
  hidden_layers=[128, 256, 128],
  test_size=0.3,
  dropout_rate=0,
)

model.fit(300)
```

#### 3.4.2 1D CNN

```python
from Qtorch.Models.Qcnn import QCNN

model = QCNN(
  data=data,
  labels=label_names,
  conv_channels=(16, 32),
  kernel_size=3,
  hidden_size=128,
  test_size=0.3,
  dropout_rate=0,
)

model.fit(300)
```

### 3.5 通用：结果获取与图表导出

```python
from Qfunctions.saveToXlsx import save_to_xlsx

pca_2d, pca_3d = model.get_PCA()
cm = model.get_cm()
cmn = model.get_cmn()
epoch_data = model.get_epoch_data()

save_to_xlsx(project_name=projet_name, file_name='pca_2d', data=pca_2d)
save_to_xlsx(project_name=projet_name, file_name='pca_3d', data=pca_3d)
save_to_xlsx(project_name=projet_name, file_name='cm', data=cm)
save_to_xlsx(project_name=projet_name, file_name='cmn', data=cmn)
save_to_xlsx(project_name=projet_name, file_name='acc_and_loss', data=epoch_data)
```

### 3.6 每次运行参数与结果 YAML 存档

当前 `main.py` 会为每次运行创建时间戳目录：

- `Result/<project_name>/<YYYYMMDD_HHMMSS>/`

并在目录下自动保存：

- `run_params.yaml`：本次运行参数快照。
- `run_result.yaml`：本次运行结果摘要（最佳轮次与最后轮次指标）。

这样可以直接对比不同运行的参数与结果变化。

## 4. load_data 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| folder | str | 必填 | `Static/` 下的数据目录名 |
| labelNames | list | 必填 | 类别名称列表，用于读取和排序标签 |

自动识别规则：

- 若每个 `label` 都对应 `folder/label/*.(xlsx|xls|csv)`，识别为多子特征模式。
- 若每个 `label` 都对应 `folder/label.(xlsx|xls|csv)`，识别为单文件模式。
- 超出支持范围的文件格式（仅支持 xls/xlsx/csv）会报错。
- 若两种都成立（同名文件和同名子目录同时存在），会报错并提示只保留一种目录结构。
- 若两种都不成立，会报错并提示检查目录结构或 `label_names`。

读取路径规则：

- 单文件模式：`./Static/folder/labelNames[i].(xlsx|xls|csv)`
- 多子特征模式：`./Static/folder/labelNames[i]/*.(xlsx|xls|csv)`

## 5. 常见问题

### 5.1 找不到文件
优先检查：

- `label_names` 与文件/文件夹是否同名
- 文件后缀是否为 `.xls`、`.xlsx` 或 `.csv`（其他格式将报错）

## 6. TODO（后续计划）

### 阶段一：基础稳定与可维护性

- [ ] 固化模型基类契约：`build_model`、输入变换钩子、统一训练配置。
- [ ] 封装 `QDL` 包结构（`qdl.data / qdl.models / qdl.export / qdl.api`）。
- [ ] 增加兼容层：保留旧导入路径，逐步迁移到新包路径。
- [ ] 增加最小测试集：`load_data`、`Qmlp.fit(1)`、`QCNN.fit(1)`、导出函数。

### 阶段二：高维与复合模型能力

- [ ] 将 batch 结构升级为字典（`x/y/lengths/mask/meta`），支持复合输入。
- [ ] 在训练框架中加入钩子：`prepare_batch`、`forward_step`、`compute_loss`。
- [ ] 引入编码器层（Encoder）抽象：按策略扩展（MLP/CNN/LSTM/GNN/Transformer），不按维度硬扩类。
- [ ] 支持可变长时间序列（`collate_fn + lengths + mask`），作为后续复合模型基础。
- [ ] 增加多分支融合模板（时序分支 + 静态分支），预留多任务损失组合。

### 阶段三：对外能力与发布

- [ ] 统一对外入口：提供高层 API（例如 `train_mlp`、`train_cnn1d`、`train_hybrid`）。
- [ ] 在模型文档中预留扩展位：`3.4.3 LSTM`、`3.4.4 GNN`、`3.4.5 Hybrid`。
- [ ] 完成打包配置（`pyproject.toml`）与本地可编辑安装说明。
- [ ] 发布前回归：在 Conda 与 pip 环境分别跑通最小端到端流程。