# seismic-deeplearning

**Repository Path**: garymade1/seismic-deeplearning

## Basic Information

- **Project Name**: seismic-deeplearning
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeismic
![DeepSeismic](./assets/DeepSeismicLogo.jpg )

此存储库向您展示如何在 Azure 上执行地震成像和解释。它使地球物理学家和数据科学家能够使用最先进的基于 DSL 的 PDE 求解器和分割算法在 Azure 上运行地震实验。

该存储库提供示例笔记本、地震数据的数据加载器、实用工具以及开箱即用的 ML 管道，组织如下：
- **示例笔记本**：这些可以在 `examples` 文件夹中找到 - 它们是标准的 Jupyter 笔记本，通过一组预制示例引导用户了解如何使用代码库
- **实验**：目标是在 `experiments` 文件夹中提供可运行的 Python 脚本，用于训练和测试（评分）我们的机器学习模型。模型本身是可交换的，这意味着通过简单地交换定义模型的配置文件，单个训练脚本可以用于在同一数据集上运行不同的模型。
- **pip 可安装实用工具**：我们提供 `cv_lib` 和 `interpretation` 实用工具（更多信息如下），这些工具被上述示例笔记本和实验使用

DeepSeismic 目前专注于地震解释（主要是相分类），并在 contrib 文件夹中提供围绕地震成像的实验代码。

以下是一个 GIF，说明了该存储库提供的功能：
[![GIF](./assets/ds.gif)](https://www.screencast.com/t/BRIad19jv)

### 快速开始

我们的存储库支持 Docker，我们提供一个 Docker 文件，您可以使用它来快速演示我们的代码库。如果您急于运行我们的代码，请按照 [Docker README](https://github.com/microsoft/seismic-deeplearning/blob/master/docker/README.md) 从 [Dockerfile](https://github.com/microsoft/seismic-deeplearning/blob/master/docker/Dockerfile) 构建和运行我们的存储库。

对于开发者，我们在下面提供更实用的快速开始。

#### 开发者快速开始
有两种方式开始使用 DeepSeismic 代码库，目前专注于解释：
- 如果您想了解我们的解释（分割）模型如何使用，只需查看 [演示笔记本](https://github.com/microsoft/seismic-deeplearning/blob/master/examples/interpretation/notebooks/Dutch_F3_patch_model_training_and_evaluation.ipynb)
- 要运行代码，您需要设置计算环境（包括设置启用 GPU 的 Linux VM 并下载适当的 Anaconda Python 包）并下载您想要使用的数据集 - 在下面的 `解释` 部分中提供了执行此操作的详细步骤。

如果您遇到任何问题，很可能您的问题已经在 [故障排除](#troubleshooting) 部分中解决了。

该笔记本设计为默认在演示模式下运行，使用预训练模型，在任何合理的深度学习 GPU（如 nVidia K80/P40/P100/V100/TitanV）上不到 5 分钟。

### Azure 机器学习
[Azure Machine Learning](https://docs.microsoft.com/en-us/azure/machine-learning/) 使您能够大规模训练和部署机器学习模型和管道，并利用开源 Python 框架，如 PyTorch、TensorFlow 和 scikit-learn。
如果您正在考虑使用此存储库中的代码与 Azure Machine Learning 入门，请参考 [Azure Machine Learning How-to](https://github.com/Azure/MachineLearningNotebooks/tree/master/how-to-use-azureml) 入门。

## 解释
对于地震解释，该存储库由可扩展的机器学习管道组成，展示了如何利用最先进的分割算法（UNet、SEResNET、HRNet）进行地震解释。
我们目前支持矩形数据，即形成 2D 矩形的 2D 和 3D 地震图像。
我们还提供 [实用工具](./examples/interpretation/segyconverter/README.md) 用于将具有矩形边界的 SEGY 数据转换为 numpy 数组，其中边界外的所有内容都已填充以产生矩形的 3D numpy 体积。

要运行存储库上可用的示例，请按照以下说明：
1) [设置环境](#setting-up-environment)
2) [下载数据集](#dataset-download-and-preparation)
3) [运行示例笔记本和脚本](#run-examples)

### 设置环境

按照以下说明阅读计算要求并安装所需库。

#### 计算环境

我们建议使用虚拟机运行示例笔记本和脚本。具体来说，您需要一个启用 GPU 的 Linux 机器，因为此存储库仅在 __Linux__ 上开发和测试。最简单的方法是使用 [Azure Data Science Virtual Machine (DSVM) for Linux (Ubuntu)](https://docs.microsoft.com/en-us/azure/machine-learning/data-science-virtual-machine/dsvm-ubuntu-intro)。此 VM 将安装创建下面描述的 conda 环境所需的所有系统要求，然后在此存储库中运行笔记本。

对于此存储库，我们建议选择类型为 [Standard_NC12](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#nc-series) 的多 GPU Ubuntu VM。该机器由 NVIDIA Tesla K80（或 NCv2 系列的 V100 GPU）供电，可在大多数 Azure 区域找到。

> 注意：对于 Azure 新用户，您的订阅可能没有 GPU 配额。您可能需要进入 Azure 门户增加 GPU VM 的配额。了解如何在此处执行：[https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits](https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits)。

#### 包安装

要安装此存储库中包含的包，导航到您拉取 DeepSeismic 存储库的目录并运行：
```bash
conda env create -f environment/anaconda/local/environment.yml
```
这将创建运行实验的适当 conda 环境。如果您在此步骤中遇到问题，请参阅 [故障排除部分](#Troubleshooting)。

接下来，您需要安装解释的公共包：
```bash
conda activate seismic-interpretation
pip install -e interpretation
```

然后您还需要安装 `cv_lib`，其中包含计算机视觉相关的实用工具：
```bash
pip install -e cv_lib
```

两个存储库都使用 `-e` 标志以开发者模式安装。这意味着要更新，只需转到文件夹并拉取适当的提交或分支。

在开发过程中，如果由于 conda env 文件更改而需要更新环境，您可以从 DeepSeismic 存储库的根目录运行
```
conda env update --file environment/anaconda/local/environment.yml
```

### 数据集下载和准备

此存储库提供如何在公开可用的注释地震数据集 [Dutch F3](https://github.com/yalaudah/facies_classification_benchmark) 上运行地震解释的示例，大小约为 2.2GB。

请确保您有足够的磁盘空间下载任一数据集。

我们有使用任一数据集的实验和笔记本。根据您想要运行的实验/笔记本，您需要下载相应的数据集。我们建议您从查看 [演示笔记本](https://github.com/microsoft/seismic-deeplearning/blob/master/examples/interpretation/notebooks/Dutch_F3_patch_model_training_and_evaluation.ipynb) 开始，该笔记本需要 Dutch F3 数据集。

#### Dutch F3 数据集准备
要下载 Dutch F3 数据集用于 2D 实验，请按照 [此 GitHub 存储库](https://github.com/yalaudah/facies_classification_benchmark)（数据集部分）中的数据下载说明。或者，您可以使用 [下载脚本](scripts/download_dutch_f3.sh)

```bash
data_dir="$HOME/data/dutch"
mkdir -p "${data_dir}"
./scripts/download_dutch_f3.sh "${data_dir}"
```
下载脚本还会自动在 `${data_dir}` 中创建数据预处理脚本所需的任何子文件夹。此时，您的 `${data_dir}` 目录应包含一个 `data` 文件夹，该文件夹应如下所示：
```bash
data
├── splits
├── test_once
│   ├── test1_labels.npy
│   ├── test1_seismic.npy
│   ├── test2_labels.npy
│   └── test2_seismic.npy
└── train
    ├── train_labels.npy
    └── train_seismic.npy
```
要为实验准备数据（例如，拆分为训练/验证/测试），请运行以下脚本：
```bash
# 更改工作目录到脚本文件夹
cd scripts

# 对于基于补丁的实验
python prepare_dutchf3.py split_train_val patch --data_dir=${data_dir}/data --label_file=train/train_labels.npy --output_dir=splits \
--stride=50 --patch_size=100 --split_direction=both

# 对于基于截面的实验
python prepare_dutchf3.py split_train_val section --data-dir=${data_dir}/data --label_file=train/train_labels.npy --output_dir=splits --split_direction=both

# 返回存储库根目录
cd ..
```
有关更多参数选项，请参考脚本本身。

#### 自带数据 [BYOD]

##### 自带 SEG-Y 数据

如果您想使用自己的地震和标签数据训练这些模型，文件需要预处理并转换为 npy 文件。通常，[segyio](https://pypi.org/project/segyio/) 可用于打开遵循标准的 SEG-Y 文件，但更常见的是，非标准设置或缺失轨迹会导致 segyio 失败。如果您的数据发生这种情况，请阅读这些笔记本和脚本以帮助准备您的数据文件：

* [SEG-Y 数据准备 README](contrib/segyconverter/README.md)
* [convert_segy.py 实用工具](contrib/segyconverter/convert_segy.py) - 可读取具有异常字节头位置和缺失轨迹的 SEG-Y 文件的实用脚本
* [segy_convert_sample 笔记本](contrib/segyconverter/segy_convert_sample.ipynb) - SEG-Y 数据转换的详细信息
* [segy_sample_files 笔记本](contrib/segyconverter/segy_sample_files.ipynb) - 创建描述转换数据到 numpy 数组时可能出现问题的场景的测试 SEG-Y 文件

##### Penobscot 示例

我们还提供启动代码，将 [Penobscot](https://arxiv.org/abs/1905.04307) 数据集（可从 [此处](https://zenodo.org/record/3924682) 获取）转换为 Dutch F3 数据集使用的 Tensor 格式 - 一旦转换，您可以通过与 Dutch F3 数据集相同的机制运行 Penobscot。粗略步骤序列是：

```bash
conda activate seismic-interpretation
cd scripts
wget -o /dev/null -O dataset.h5 https://zenodo.org/record/3924682/files/dataset.h5?download=1
# 转换 penobscot
python byod_penobscot.py --filename dataset.h5 --outdir <输出数据的位置>
# 为实验预处理
python prepare_dutchf3.py split_train_val patch --data_dir=<上一步的 outdir> --label_file=train/train_labels.npy --output_dir=splits --stride=50 --patch_size=100 --split_direction=both --section_stride=100
```

### 运行示例

#### 笔记本
我们在 `examples/interpretation/notebooks/` 下提供示例笔记本，以演示如何训练地震解释模型并在 Penobscot 和 F3 数据集上评估它们。

确保在之前设置的 conda 环境中运行笔记本（`seismic-interpretation`）。要在 Jupyter 中注册 conda 环境，请运行：
```
python -m ipykernel install --user --name seismic-interpretation
```
__可选__：如果您计划开发笔记本，您可以使用以下命令安装 black 格式化器：
```bash
conda activate seismic-interpretation
jupyter nbextension install https://github.com/drillan/jupyter-black/archive/master.zip --user
jupyter nbextension enable jupyter-black-master/jupyter-black
```
这将为您的笔记本启用 Black 格式化器按钮，单击后将自动格式化您所在的笔记本单元格。

#### 实验

我们还为使用不同分割方法进行的许多实验提供脚本。这些实验可在 `experiments/interpretation` 下找到，并可用作示例。在每个实验中，从 `train.sh` 和 `test.sh` 脚本开始，这些脚本调用相应的 python 脚本 `train.py` 和 `test.py`。查看实验配置（请参阅下面的实验配置文件部分）以获取实验选项并根据需要修改。

此版本目前支持 Dutch F3 本地和分布式训练
- [Dutch F3 Patch](experiments/interpretation/dutchf3_patch/README.md)

请注意，我们使用 [NVIDIA 的 NCCL](https://docs.nvidia.com/deeplearning/nccl/install-guide/index.html) 库启用分布式训练。请按照 [此处](https://docs.nvidia.com/deeplearning/nccl/install-guide/index.html#down) 的安装说明在您的系统上安装 NCCL。

#### 配置文件
我们使用 [YACS](https://github.com/rbgirshick/yacs) 配置库管理实验的配置选项。有三种方式将参数传递给实验脚本（例如 train.py 或 test.py）：

- __default.py__ - 项目配置文件 `default.py` 是所有可配置选项的一站式参考点，并为所有参数提供合理的默认值。如果没有参数传递给 `train.py` 或 `test.py` 脚本（例如 `python train.py`），参数默认从 `default.py` 加载。请查看 `default.py` 以熟悉脚本使用的实验参数。

- __yml 配置文件__ - `configs/` 下的 YAML 配置文件通常为每个实验创建一个。这些旨在用于可重复的实验运行和可重现的设置。每个配置文件仅覆盖该实验中正在更改的选项（例如，在实验运行期间从 `defaults.py` 加载的选项将被从 yaml 文件加载的参数覆盖）。例如，要使用 yml 配置文件与训练脚本，请运行：
    ```
    python train.py --cfg "configs/seresnet_unet.yaml"
    ```

- __命令行__ - 最后，可以通过 `options` 参数传递选项，这些选项将覆盖从配置文件加载的参数。我们为所有脚本创建了 CLI（使用 Python Fire 库），因此您可以通过命令行参数传递这些选项，如下所示：
    ```
    python train.py DATASET.ROOT "/home/username/data/dutch/data" TRAIN.END_EPOCH 10
    ```

#### 训练
我们运行一个激进的余弦退火调度，从更高的学习率 (LR) 开始，并在约 60 个周期内逐渐降低到零，此时我们将 LR 提高回其原始值并再次降低约 60 个周期；此过程继续 5 次，形成 60*5=300 个训练周期，总共 5 个周期；在每个周期中，具有最佳频率加权 IoU 的模型被快照到磁盘。我们建议咨询 TensorBoard 日志以查看哪个训练周期产生了最佳模型，并在评分期间使用该模型。

对于多 GPU 训练，我们在开始 5 个余弦周期之前运行线性烧入 LR 调度，然后训练以与单 GPU 相同的方式继续。

### 预训练模型

此存储库使用两种类型的预训练模型：
1. 在非地震计算机视觉数据集上训练的预训练模型，我们通过在地震数据上重新训练来微调它们以适应地震领域
2. 我们已经在地震数据上训练的模型 - 如果需要，这些模型由我们的代码自动下载（再次，请参阅上面的笔记本以获取演示如何执行此操作）。

### 查看器（可选）

对于地震解释（分割），如果您想可视化 3D 体积的横截面（输入速度模型和分割输出），您可以使用 [segyviewer](https://github.com/equinor/segyviewer)。要安装和使用 segyviewer，请按照以下说明操作。

#### segyviewer

要安装 [segyviewer](https://github.com/equinor/segyviewer)，请运行：
```bash
conda env create -n segyviewer python=2.7
conda activate segyviewer
conda install -c anaconda pyqt=4.11.4
pip install segyviewer
```

要可视化 3D 体积的横截面，您可以运行 [segyviewer](https://github.com/equinor/segyviewer) 如下：
```bash
segyviewer "${HOME}/home/username/data/dutch/data.segy"
```

### 基准

#### 密集标签

此部分包含在具有密集注释数据的 3D 地震数据集上使用不同算法进行地震解释的基准。我们目前仅支持此版本的单 GPU Dutch F3 数据集基准。

#### Dutch F3

| 来源         | 实验                                | PA    | FW IoU | MCA  | 单 V100 (16GB) GPU 训练时间 | 四 V100 (16GB) GPU 训练时间 |
| -------------- | ----------------------------------------- | ----- | ------ | ---- | ------------------------------------ | ----------------------------------- |
| Alaudah 等 | 基于截面的                             | 0.905 | 0.817  | .832 | N/A                                  | N/A                                 |
|                | 基于补丁的                               | 0.852 | 0.743  | .689 | N/A                                  | N/A                                 |
| DeepSeismic    | 基于补丁+固定                         | .892  | .811   | .759 | 18h 42min                            | 7h 24min                            |
|                | 基于补丁+固定+跳过                    | .909  | .839   | .802 | 19h 01min                            | 7h 39min                            |
|                | SEResNet UNet+截面深度               | .928  | .872   | .866 | ~9 天                              | 35h 54min                           |
|                | HRNet(补丁)+截面深度 (实验性) | .926  | .869   | .873 | ~10 天                             | 43h 9min                            |

注意：这些是单次运行性能数字，我们期望结果在不同运行之间波动，即预期有一些变异性，但我们期望使用此代码库的性能数字接近这些。

#### 重现基准
为了重现基准，您需要导航到 [experiments](experiments) 文件夹。在那里，每个实验分为不同的文件夹。要运行 Dutch F3 实验，导航到 [dutchf3_patch](experiments/interpretation/dutchf3_patch/) 文件夹。在那里有一个训练脚本 [train.sh](experiments/interpretation/dutchf3_patch/train.sh)，它将为您传入的任何配置运行训练。如果您的机器有多个 GPU，您可以使用分布式训练脚本 [train_distributed.sh](experiments/interpretation/dutchf3_patch/train_distributed.sh) 运行分布式训练。一旦您运行了训练，您将需要运行 [test.sh](experiments/interpretation/dutchf3_patch/test.sh) 脚本。确保指定从您的训练运行中最佳性能模型的路径，通过将其作为参数传入或更改 YACS 配置文件。

## 贡献

此项目欢迎贡献和建议。大多数贡献要求您同意贡献者许可协议 (CLA)，声明您有权并实际授予我们使用您的贡献的权利。有关详细信息，请访问 [https://cla.opensource.microsoft.com](https://cla.opensource.microsoft.com)。

### 提交拉取请求

我们努力保持存储库处于清洁状态，这意味着我们仅启用对存储库的读取访问 - 读取访问仍允许提交 PR 或问题。为此，请分叉存储库，并从您分叉存储库的分支提交 PR 到我们的暂存分支。

当您提交拉取请求时，CLA 机器人将自动确定您是否需要提供 CLA 并相应地装饰 PR（例如，状态检查、评论）。只需按照机器人提供的说明操作。您只需在所有使用我们 CLA 的存储库中执行一次此操作。

此项目已采用 [Microsoft 开源行为准则](https://opensource.microsoft.com/codeofconduct/)。有关更多信息，请参阅 [行为准则 FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 或通过 [opencode@microsoft.com](mailto:opencode@microsoft.com) 联系我们以获取任何其他问题或评论。

## 构建状态
| 构建                | 分支  | 状态                                                                                                                                                                                                                                                               |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **法律合规** | 暂存 | [![构建状态](https://dev.azure.com/best-practices/deepseismic/_apis/build/status/microsoft.ComponentGovernance%20(seismic-deeplearning)?branchName=staging)](https://dev.azure.com/best-practices/deepseismic/_build/latest?definitionId=124&branchName=staging) |
| **法律合规** | 主分支  | [![构建状态](https://dev.azure.com/best-practices/deepseismic/_apis/build/status/microsoft.ComponentGovernance%20(seismic-deeplearning)?branchName=master)](https://dev.azure.com/best-practices/deepseismic/_build/latest?definitionId=124&branchName=master)   |
| **核心测试**       | 暂存 | [![构建状态](https://dev.azure.com/best-practices/deepseismic/_apis/build/status/microsoft.Tests%20(seismic-deeplearning)?branchName=staging)](https://dev.azure.com/best-practices/deepseismic/_build/latest?definitionId=126&branchName=staging)               |
| **核心测试**       | 主分支  | [![构建状态](https://dev.azure.com/best-practices/deepseismic/_apis/build/status/microsoft.Tests%20(seismic-deeplearning)?branchName=master)](https://dev.azure.com/best-practices/deepseismic/_build/latest?definitionId=126&branchName=master)                 |

# 故障排除

对于数据科学虚拟机 conda 包安装问题，请确保在 DSVM 上定位 anaconda 位置，例如通过运行：
```bash
which python
```
典型输出将是：
```bash
someusername@somevm:/projects/DeepSeismic$ which python
/anaconda/envs/py35/bin/python
```
这将指示 anaconda 文件夹是 `__/anaconda__`。我们将在下面的说明中引用此位置，但您应根据本地 anaconda 文件夹更新命令。

<details>
  <summary><b>数据科学虚拟机 conda 包安装错误</b></summary>

  可能发生的情况是您没有足够的权限运行 conda 命令/在 Anaconda 包目录中安装包。要解决这种情况，请运行以下命令
  ```bash
  rm -rf /anaconda/pkgs/*
  sudo chown -R $(whoami) /anaconda
  ```

  在这些命令完成后，再次尝试安装包。

</details>

<details>
  <summary><b>数据科学虚拟机 conda 包安装警告</b></summary>

  可能发生的情况是在 Ubuntu DSVM 上创建由 `environment/anaconda/local/environment.yml` 定义的 conda 环境时，可以获得多个警告，如下所示：
  ```bash
  WARNING conda.gateways.disk.delete:unlink_or_rename_to_trash(140): Could not remove or rename /anaconda/pkgs/ipywidgets-7.5.1-py_0/site-packages/ipywidgets-7.5.1.dist-info/LICENSE.  Please remove this file manually (you may need to reboot to free file handles)  
  ```
    
  如果发生这种情况，与上面的说明类似，停止 conda 环境创建（键入 ```Ctrl+C```）然后递归更改 `/anaconda` 目录的所有权从 root 到当前用户，通过运行此命令： 

  ```bash
  sudo chown -R $USER /anaconda
  ```

  在此命令完成后，再次尝试在 `__environment/anaconda/local/environment.yml__` 中创建 conda 环境。

</details>

<details>
  <summary><b>模型训练或评分未使用 GPU</b></summary>

  要查看在您的模型被训练或用于推理时是否正在使用 GPU，请运行
  ```bash
  nvidia-smi
  ```
  并确认您看到您的 Python 进程正在使用 GPU。

  如果没有，您可能想要尝试回退到较旧版本的 CUDA 以与 PyTorch 一起使用。在设置环境后，在运行 `conda activate seismic-interpretation` 激活 conda 环境后运行以下命令（默认情况下我们使用 CUDA 10）：
  ```bash
  conda install pytorch torchvision cudatoolkit=9.2 -c pytorch
  ```

  要测试此设置是否有效，您可以打开 `ipython` 并执行以下代码
  ```python
  import torch
  torch.cuda.is_available() 
  ```

  输出应显示 `True`。如果输出仍然是 `False`，您可能想要尝试手动设置环境变量以指定设备 - 要测试此，请启动新的 `ipython` 会话并键入：
  ```python
  import os
  os.environ['CUDA_VISIBLE_DEVICES']='0'
  import torch                                                                                  
  torch.cuda.is_available() 
  ```
  输出这次应显示 `True`。如果确实如此，您可以通过添加以下内容使更改永久：
  ```bash
  export CUDA_VISIBLE_DEVICES=0
  ```
  到您的 `$HOME/.bashrc` 文件。

</details>

<details>
  <summary><b>GPU 内存不足错误</b></summary>

  您应该能够通过运行查看您的进程正在使用多少 GPU 内存：
  ```bash
  nvidia-smi
  ```
  并查看此数量是否接近 GPU 制造商指定的物理内存限制。

  如果我们接近内存限制，您可能想要在模型配置文件中降低批大小。具体来说，`TRAIN.BATCH_SIZE_PER_GPU` 和 `VALIDATION.BATCH_SIZE_PER_GPU` 设置。

</details>

<details>
  <summary><b>如何调整数据科学虚拟机磁盘大小</b></summary>

  1. 转到 [Azure 门户](https://portal.azure.com) 并通过在页面顶部搜索栏中键入其名称来查找您的虚拟机。

  2. 在左侧的概述面板中，单击停止按钮以停止虚拟机。

  3. 接下来，在同一面板左侧选择磁盘。

  4. 单击 OS 磁盘的名称 - 您将被导航到磁盘视图。从此视图中，在左侧选择配置，然后增加 GB 中的大小并点击保存按钮。

  5. 导航回步骤 2 中的虚拟机视图并单击开始按钮以启动虚拟机。

</details>