# PhysPick

**Repository Path**: maergaiyun/phys-pick

## Basic Information

- **Project Name**: PhysPick
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 地震初至自动拾取项目

本项目用于地震记录的初至自动拾取。当前版本已经完成三阶段训练、人工修正实测数据微调、独立测试评估和交付包整理。

## 当前结论

当前最优模型可以直接用于新的 SEG-Y 数据自动拾取。

- 最优模型：`outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze/best.ckpt`
- 训练口径：Stage-1 Synthetic -> Stage-2 Semi-real -> Stage-3 Human-reviewed Field
- 采样间隔：`dt = 2000 us`
- 自动拾取程序：`scripts/infer_firstbreak_autopick.py`

最终评估结果：

| 测试场景 | MAE (sample/px) | 约合时间误差 |
|---|---:|---:|
| 内部 test | 1.3594 | 2.72 ms |
| 独立集 random | 1.4714 | 2.94 ms |
| 独立集 lowconf | 1.4219 | 2.84 ms |

说明：

- `内部 test`：人工修正 30 炮数据内按训练划分留出的测试集。
- `独立集 random`：随机抽取的独立测试炮，用于评估常规泛化能力。
- `独立集 lowconf`：低置信度/困难样本独立测试炮，用于评估强噪声、弱初至、面波干扰等场景下的鲁棒性。

交付口径建议：

> 模型已在内部测试、随机独立测试和困难样本独立测试三类场景验证。独立测试误差约为 1.42-1.47 个采样点，在 2 ms 采样间隔下约为 2.84-2.94 ms，可用于后续实测数据初至自动拾取。对强噪声、初至弱、面波干扰明显的炮，建议保留人工复核流程。

## 目录结构

```text
configs/                         # 训练配置
docs/                            # 方案说明和记录
scripts/                         # 数据生成、训练、评估、推理脚本
data/                            # 数据目录，默认不纳入 git
outputs/                         # 模型和评估结果，默认不纳入 git
deliverables/                    # 对外交付 zip 包，默认不纳入 git
```

关键数据目录：

```text
data/04_stage3_field/dt2ms/human_reviewed_30shots
data/04_stage3_field/dt2ms/human_reviewed_30shots_refined
data/04_stage3_field/dt2ms/pseudo_labeled_30shots
```

关键输出目录：

```text
outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze
outputs/independent_eval
outputs/stage3_pseudo30
```

## 环境依赖

主要依赖：

- Python 3.9+
- PyTorch
- NumPy
- Pandas
- segyio
- PyYAML

示例安装：

```bash
pip install torch numpy pandas segyio pyyaml
```

如使用 GPU，需按本机 CUDA 版本安装对应 PyTorch。

## 对新 SEG-Y 自动拾取

使用训练好的网络模型对新的未标注 SEG-Y 自动拾取：

```bash
python scripts/infer_firstbreak_autopick.py \
  --input-sgy /path/to/input.sgy \
  --checkpoint outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze/best.ckpt \
  --output-dir outputs/autopick_new \
  --device auto \
  --threshold 0.5
```

输出内容：

```text
outputs/autopick_new/
  autopick_all_traces.csv          # 所有道的拾取结果
  autopick_shot_summary.csv        # 每炮统计信息
  autopick_meta.json               # 推理元信息
  labels_by_shot/                  # 每炮一个标签 CSV
```

`autopick_all_traces.csv` 主要字段：

- `shot_id`
- `trace_index`
- `trace_number`
- `offset`
- `pick_sample`
- `pick_time_ms`
- `confidence`
- `dt_us`

客户常问问题：

> 训练好的模型是否能单独用于待测数据拾取？

可以。训练完成后模型权重固定，后续对新的 SEG-Y 数据不需要重新训练，只需调用 `scripts/infer_firstbreak_autopick.py` 加载模型和待测数据，即可批量输出每炮每道的初至拾取结果。

## 训练最优 Stage-3 模型

当前最优配置：

```text
configs/stage3_human30_ft_from_p3_lr2e5_unfreeze.yaml
```

训练命令：

```bash
python scripts/train_firstbreak_stage.py \
  --config configs/stage3_human30_ft_from_p3_lr2e5_unfreeze.yaml \
  --num-workers 4
```

训练结果：

```text
outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze/
  best.ckpt
  last.ckpt
  metrics.csv
  summary.yaml
```

## 评估模型

随机独立测试集：

```bash
python scripts/evaluate_checkpoints_on_split.py \
  --split-csv data/04_stage3_field/dt2ms/human_reviewed_30shots/independent_split_random/stage3_independent_test.csv \
  --checkpoints outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze/best.ckpt \
  --output-csv outputs/independent_eval/eval_random.csv
```

困难样本独立测试集：

```bash
python scripts/evaluate_checkpoints_on_split.py \
  --split-csv data/04_stage3_field/dt2ms/human_reviewed_30shots/independent_split_lowconf/stage3_independent_test.csv \
  --checkpoints outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze/best.ckpt \
  --output-csv outputs/independent_eval/eval_lowconf.csv
```

已有评估文件：

```text
outputs/independent_eval/human30_ft_lr2e5_vs_unfreeze_random.csv
outputs/independent_eval/human30_ft_lr2e5_vs_unfreeze_lowconf.csv
```

## 三阶段训练思路

1. Stage-1 Synthetic

使用大量合成数据预训练模型，学习基础初至形态和走时规律。

2. Stage-2 Semi-real

使用公开数据和半真实数据做域适配，提升模型对噪声、振幅变化和不同道集形态的鲁棒性。

3. Stage-3 Human-reviewed Field

使用 30 炮人工修正实测数据微调，使模型适配目标工区数据。

## 创新点整理

当前项目可总结为：

- 少量人工修正实测数据驱动的现场适配。
- 三阶段课程学习：Synthetic -> Semi-real -> Field。
- 不确定性/低置信度样本评估，用 `lowconf` 独立集验证困难样本鲁棒性。
- 物理约束和平滑修复做过实验验证；当前最终模型以实测独立集表现为准，未强行加入会降低指标的约束项。

## 交付文件

代码包：

```text
deliverables/dizhen_code_only_20260517.zip
```

数据包：

```text
deliverables/human_reviewed_30shots_20260524.zip
deliverables/human_reviewed_30shots_refined_20260524.zip
```

说明：

- `human_reviewed_30shots` 是人工修正口径数据。
- `human_reviewed_30shots_refined` 是轻微尖刺修复版，最终指标与原版一致。
- 模型交付建议使用 `outputs/stage3_human30_ft_from_p3_lr2e5_unfreeze/best.ckpt`。

## Git 说明

`.gitignore` 已忽略：

- `data/`
- `outputs/`
- `deliverables/`
- Python 缓存和日志文件

源码、配置和文档可以进入 git；数据、模型权重和交付压缩包默认不进入 git。