Skip to content
BranchesTags
 
 

Repository files navigation

FastXC

English | 三步快速使用 | App 图文全参数说明书 | 本地 Workspace App | 文档索引 | 背景噪声交付回报（PDF） | 配置说明 | 架构说明 | 输出说明 | 工具命令 | 结果策略 | 更新日志

本项目的 v2605 公开整理、文档重写和发布打包过程使用了 OpenAI Codex / GPT Pro 辅助。

FastXC 是一套面向 SAC 波形数据的环境噪声互相关计算流程。Python 层负责配置 解析、SAC inventory、路径规划、阶段调度和索引格式；计算层可自动选择 CUDA 或便携 CPU 后端。macOS/Linux/Windows 的 CPU 后端支持 SAC2SPEC、指定路径互 相关和 linear stack；Linux/WSL + NVIDIA CUDA 后端同时支持 PWS 和 TF-PWS。 原生 Windows 当前使用 CPU，不运行 Linux CUDA 二进制。

获取代码

从 GitHub clone 或解压发布包后，先进入项目根目录：

git clone https://github.com/wangkingh/FastXC.git FastXC
cd FastXC

# 或者解压发布包
tar -xf FastXC*.tar.gz
cd FastXC*

环境要求

  • Python 3.10 或更新版本。
  • Python 依赖：numpy、pandas、scipy、tqdm。
  • CPU 模式：macOS、Linux 或 Windows，不需要 CUDA。
  • CUDA 模式：NVIDIA CUDA Toolkit、可用 GPU、GNU Make 和 C/CUDA 工具链， 运行于 Linux 或 WSL。

CUDA 架构默认自动检测。如果自动检测失败，可以手动指定：

make install ARCH=sm_89

其中 ARCH 应该按当前 GPU 的 compute capability 设置，例如 8.9 对应 sm_89，12.0 对应 sm_120。也可以写成 sm89、sm120 或 8.9、 12.0，构建系统会规范化为 sm_XX。如果更换 GPU、修改 ARCH，或怀疑已有 bin/ 里的原生二进制是按旧架构编译的，请先清理旧 native 产物再安装：

make veryclean-native
make install BUILD=release ARCH=sm_XX

把 sm_XX 替换成当前 GPU 对应的架构；自动检测正常时也可以省略 ARCH。 通常不需要手动设置编译器路径。只有当 make 选到了不完整或错误的 nvcc 时，才显式指定 NVCC/CUDA_HOME，例如：

make veryclean-native
make install BUILD=release ARCH=sm_XX \
  NVCC=/path/to/cuda/bin/nvcc CUDA_HOME=/path/to/cuda

如果使用 Miniconda/Conda 里的 CUDA，请确认该环境提供完整 CUDA Toolkit， 包括 nvcc、cufft.h 和 libcufft.so。构建系统会同时检查 $CUDA_HOME/include 和 $CUDA_HOME/targets/x86_64-linux/include 这类布局。 当 nvcc 不兼容默认 host compiler 时，再指定真实存在的 C/C++ 编译器：

make veryclean-native
make install BUILD=release ARCH=sm_XX CC=/path/to/gcc CXX=/path/to/g++

安装

下面所有命令都假设当前目录是 FastXC 项目根目录，也就是能看到 README.md、Makefile、fastxc/、native/ 和 example/ 的目录。

只使用 CPU（包括 Apple Silicon Mac）时，在项目根目录执行：

python -m pip install -e .
fastxc doctor

需要 CUDA 完整后端时执行：

# 先进入任意 Python >= 3.10 环境。
make install
fastxc doctor

make install 会编译所有受支持的原生后端、把可执行文件部署到 Python 包， 并安装可编辑的 fastxc 命令。CPU 安装不会编译或运行 native/ 中的 Linux CUDA 文件。

如果只想编译原生二进制、不安装 Python 包：

make native-full      # 编译 sac2spec、xc_fast、ncf_pws、ncf_tfpws
make stage-binaries   # 把编译好的二进制复制进 fastxc/bin/<platform>

原生二进制会写入 bin/，用于 Python 包分发的 staged binaries 会写入 fastxc/bin/<platform>/。

两种运行方式

FastXC 支持两种等价的命令风格：

# 源码树风格：适合还没有安装 fastxc 命令时使用。
python -m fastxc.cli doctor config.ini
python -m fastxc.cli prepare config.ini
python -m fastxc.cli run config.ini

# 包化 CLI 风格：执行 make install 或 pip install -e . 后可用。
fastxc doctor config.ini
fastxc prepare config.ini
fastxc run config.ini

两种方式调用的是同一个 Python 入口。fastxc ... 更短；python -m fastxc.cli ... 更适合直接在源码目录里调试，或者环境还没有完整安装 console command 的时候使用。

最快工作流

普通用户只需：

fastxc init -o config.ini
# 只修改 config.ini 中的 sac_dir
fastxc run config.ini

简化配置会从 SAC 头段自动识别台站、分量、时间和采样间隔；自动选择本机 CPU/CUDA，并生成不含自相关和反向重复的全部台站路径。连续率筛选和 SNR 默认 关闭，需要时显式启用。生成的 INI 还包含中文逐项注释的 [workflow]，可直接用 run/skip/auto 选择处理阶段，日常运行不需要改 Python 文件或追加 flag。完整说明见 三步快速使用。

专家工作流

FastXC 围绕可复用 inventory 运行：

fastxc prepare config.ini
fastxc run config.ini

prepare 会扫描 SAC 文件、分配 NSL ID、生成 SAC index、筛选允许路径，并写 出 inventory 元数据。run 会读取准备好的 inventory，依次执行频谱转换、互 相关、SourcePack 整理、叠加、旋转和可选导出。

需要前端在启动计算前展示任务量时，在 [advance.compute] 设置 estimate_enabled = True；同一条 prepare 会原子生成默认位于 workspace_dir/frontend/compute_estimate.json 的版本化报告，不需要新增 CLI 参数。

需要前端按需展示频谱时，在 [frontend_products] 同时启用 enabled 和 spectrum_tsv_enabled。Sac2Spec 后会发布频谱目录；页面把版本化 JSON 请求原子 写入固定 request_dir/spectrum/，再从 response_dir/spectrum/ 读取图表 TSV 和 状态 JSON。查询只读目标 StepPack 字节范围，不新增台站/时间 CLI flag，也不重算 频谱或互相关。

需要为每日 NCF 计算 SNR 时，在 [ncf_quality] 明确配置方法、信号窗、噪声窗、 可选频段和 user3..user9 头段。FastXC 会保留原始 ncf/xcpack，事务生成质量 增强派生包与 frontend/ncf_snr.tsv；SourcePack 随后同步读取派生包。科研参数未 确认时保持 enabled = False。简化 [fastxc] 配置可直接设置 snr_method、 snr_waveform、signal_window、noise_window、snr_freqmin 和 snr_freqmax； fastxc snr 成功后记录最近一次运行快照，App 会据此显示真实启用状态。

也可以只运行某个后续阶段。下面这些命令仍然读取同一个 config.ini，不需要 手动填写 native SAC2SPEC/XC/PWS/TF-PWS 的底层参数：

fastxc sac2spec config.ini
fastxc products config.ini         # 只处理已有频谱/NCF 的前端查询
fastxc xc config.ini              # XC 后默认整理 SourcePack
fastxc xc config.ini --no-sourcepack
fastxc snr config.ini             # 只基于已有每日 NCF 刷新 SNR，不重算频谱/XC/叠加
fastxc stack config.ini             # 排除后重叠加并刷新 Rotate/Unpack/Dashboard
fastxc stack config.ini --method linear,pws,tfpws  # 仅调试指定 Stack 阶段
fastxc rotate config.ini

它们适合已有 workspace 的补跑和调试；完整生产计算仍推荐 prepare + run。前端 写入频谱/NCF 请求 JSON 后应调用 products，不要为了查询再次执行完整 run。

辅助工具速查

主流程仍建议使用 prepare + run；需要补跑计算阶段时见上一段。下面只列检查 中间结果、手动导出和绘图等辅助工具：

场景 命令
SAC 转 dat fastxc sac2dat -I ... -O ...
手动构建 SourcePack fastxc sourcepack -I ... -O ...
从 SourcePack 导出 SAC fastxc unpack -I ... -O ...
抽取单条 NCF SAC 记录 fastxc extract-ncf --workspace ... --timestamp ... --source ... --receiver ... --component-pair ... -O ...
绘制 result_ncf 虚拟源炮集 fastxc plot-rtz-grid -I ... --source ...
抽取并绘制某个 StepPack 台站频谱 fastxc extract-stepack --workspace ... --timestamp ... --station ... --plot
重绘已导出的频谱 MAT fastxc plot-stepack-mat -I ... -O ...

plot-rtz-grid 会按结果分量数自动使用单图或 3x3 九宫格；extract-ncf 可从 SourcePack/XC pack 索引中复制单条 NCF SAC，不会重算 XC；extract-stepack --plot 会同时写 .mat 和快速检查 PNG。更完整参数见 工具命令。

生成完整专家配置

生成配置文件：

fastxc init --full -o config.full.ini

修改 config.full.ini 后执行：

fastxc doctor config.full.ini
fastxc prepare config.full.ini
fastxc run config.full.ini

内置示例

仓库包含一套小型匿名三分量 SAC 数据：

example/

示例目录的详细说明见 example/README.md。

安装完成并确认 fastxc doctor 正常后，在仓库根目录运行简化示例：

fastxc run configs/easy_example.ini

也可以使用原有完整示例：

cd example
fastxc doctor config.ini
fastxc prepare config.ini
fastxc run config.ini

示例 workspace 会写入：

workspace

可选绘图检查不属于标准计算流程，只用于本地查看结果。继续留在 example/ 目录中执行。如果当前环境还没有 matplotlib，先安装它：

python -m pip install matplotlib

然后可以把旋转后的 RTZ 叠加结果画成按距离偏移的 line plot。默认只叠加 ZZ、ZR、RZ 三个分量，用不同颜色标注，便于查看相位差：

python plot_rtz_distance_lines.py \
  --workspace workspace \
  --lag-window 20 \
  --output workspace/plots/rtz_linear_zz_zr_rz_distance_lines.png

该命令只读取 stack/rtz_*_sourcepack 下的 RTZ 结果；如果启用了 PWS 或 TF-PWS，可通过 --method pws 或 --method tfpws 绘制对应叠加结果。 如果已经通过 unpack 导出了 result_ncf/ 下的 SAC 文件，也可以使用 fastxc plot-rtz-grid 绘制单分量或 RTZ/ENZ 九分量虚拟炮集；详见 工具命令。

主要配置项

使用完整专家配置时通常主要修改这些字段：

[seisarray1]
sac_dir = /path/to/sac/root
pattern = {home}/{station}/{YYYY}/{station}.{YYYY}.{JJJ}.{*}.{component}.{suffix}
sta_list = NONE
component_list = E,N,Z

[time_filter]
time_start = 2017-09-01 00:00:00
time_end = 2017-09-30 01:00:00
time_list = NONE

[geometry]
external_geo_tsv = NONE

[quality_control]
enabled = False
continuity_method = header_coverage
window_sec = 3600
summary_window_sec = 259200
min_continuity = 0.0
reject_policy = exclude
station_quality_tsv = frontend/station_quality.tsv
eligible_station_tsv = frontend/eligible_stations.tsv

[compute]
sac_len = 86400
win_len = 3600
shift_len = AUTO
delta = 0.1
normalize = AUTO
bands = 0.1/2
whiten = AFTER
max_lag = 100
stack_flag = 100
workspace_dir = /path/to/output/workspace

[device]
backend = auto
gpu_list = 0
cpu_workers = 20

[advance.compute]
skip_step = -1
phase_only = False
distance_range = -1/50000
azimuth_range = -1/360
group_pair_mode = all
autocorr_mode = off
path_file = NONE
path_file_missing_policy = error
async_poll_sec = 5
sourcepack_async_after_xc = True
pre_stack_size = 10
tfpws_band = FULL
tfpws_taper_hz = AUTO

[advance.storage]
unpack_enabled = True
unpack_target = ALL

[debug]
debug = False

其中 pattern 描述 sac_dir 下 SAC 文件的相对路径。它必须从 {home} 开 始，并至少包含 {station}、{component} 或 {channel}，以及能解析日期的 字段，例如 {YYYY} + {JJJ} 或 {YYYY} + {MM} + {DD}。常用通配符： {*} 匹配任意字符串，{?} 匹配一个较短的非路径片段；重复出现的同名字段 必须取相同值。更完整的字段和 pattern 规则见 配置说明。

sta_list 是每个 [seisarrayN] 或 [seisarrayN.source] 自己的台站白名 单；NONE 表示这个数据源不按台站筛选。文件格式是一行一个 station code， 空行和 # 开头的注释行会被忽略。多个 source 合并到同一组时，每个 source 先按自己的 sta_list 过滤，再合并到同一个 group。

常用字段格式：

  • time_start/time_end：YYYY-MM-DD HH:MM:SS。
  • time_list：一行一个时间，推荐 YYYY-MM-DD HH:MM:SS；空行和 # 注释 会被忽略；NONE 表示使用 time_start/time_end。
  • bands：空格分隔的 fmin/fmax 频带，例如 0.2/0.4 0.1/0.2。
  • shift_len：秒数，或 AUTO；AUTO 等于 win_len。
  • max_lag：互相关最大延迟，单位秒。
  • stack_flag：三位 0/1，依次控制 linear/PWS/TF-PWS，例如 100 只做 linear，111 三种都做。
  • backend：auto 自动选择；在有兼容二进制和可见 NVIDIA GPU 时选 CUDA， 否则选 CPU。也可明确写 cpu 或 cuda。CPU 模式必须使用 stack_flag = 100。
  • distance_range：min/max，单位 km；-1/50000 基本等于不限制。
  • azimuth_range：min/max，单位度；-1/360 基本等于不限制。
  • group_pair_mode：intra 只算同组，inter 只算组间，all 全部计算。
  • autocorr_mode：自相关路径开关。off 关闭自相关，include 在普通台站对 之外加入自相关，only 只保留自相关。
  • path_file：可选的两列 TSV 精确路径表，第一列 source，第二列 receiver。NONE 使用原有自动配对；指定文件后，prepare 只检查文件中的 路径，不再枚举全部台站组合。
  • path_file_missing_policy：error 表示缺少 path 文件时报错；wait 表示先 输出连续率和可用台站表，并停在 WAITING_FOR_PATH_FILE 等待前端选台。

例如只计算 A-B、A-C，可以建立 selected_paths.tsv：

source	receiver
A	B
A	C

然后在 INI 的 [advance.compute] 中写 path_file = selected_paths.tsv，照常执行 fastxc prepare config.ini 和 fastxc run config.ini。A-B/B-A 会规范化为同一条 内部路径；未列出的 B-C 和各台站自相关不会进入计算。

macOS/CPU 的完整安装、INI 示例、能力边界和 CUDA 对照结果见 CPU 后端使用与验证。 四条广西真实 SAC 的 Mac/Linux CPU 全路径复现、虚拟炮集对比和定量误差见 广西真实数据 Mac/Linux CPU 验证。

需要“先看连续率、再由前端选台”时，可启用 [quality_control]，把 path_file 指向前端将要生成的文件，并设置 path_file_missing_policy = wait。第一次 prepare 会生成 workspace/frontend/station_quality.tsv 和 eligible_stations.tsv 后正常结束； 前端原子写入两列路径 TSV 后再次执行同一条 prepare 即可。当前 header_coverage 只按 SAC 时间戳与 NPTS/DELTA 计算覆盖率，不把零值直接判为 坏数据。

[geometry].external_geo_tsv 用于提供外部台站坐标表。NONE 表示从 SAC header 的 STLA/STLO/STEL 读取坐标；当 SAC header 缺少坐标、坐标不可靠， 或者同一 station 需要按 network/location 区分坐标时，可以把它设为 一个 TSV 文件路径。TSV 至少需要 station、lat、lon 三列，也兼容 latitude、longitude；可选列包括 ele/elevation、network、 location。group 是 FastXC 内部的逻辑分组，不参与外部坐标匹配。如果同 时提供 network 和 location，FastXC 会优先按 network + station + location 匹配；否则按 station 匹配。经纬度使用十进制度，西经和南纬写负 数。相对路径按执行 fastxc 命令时的当前目录解析；建议使用绝对路径，或在配 置文件所在目录运行。

station	lat	lon	network	location
A7K2	38.499907	-98.603619	KS	00

输出结构

fastxc prepare 会在 workspace_dir 下写出：

inventory.meta.json
manifest/sac_index.tsv
path_plan/allowed_paths.tsv
path_plan/nsl_catalog.tsv

fastxc run 会继续写出：

commands/
filter.txt
stepack/
ncf/
sourcepack/
stack/
stack/rtz_*_sourcepack/
result_ncf/
progress/
log/

commands/ 会保留 Python 实际调用的 native 命令，便于审查和复现。 各阶段产物的用途、是否可清理、以及 SourcePack/stack/rotate 的关系见 输出说明。

如何理解中间结果

FastXC 当前主线尽量避免在计算阶段生成海量散 SAC 文件。中间结果通常是：

pack 二进制大文件 + sourcepack_index.tsv 索引

SAC2SPEC 先写 stepack/，XC 直接读取这些 worker-batch 频谱文件；XC 的互相关 结果写入 ncf/xcpack/。随后 SourcePack 阶段把这些记录整理成 sourcepack/<timestamp>/sourcepack_index.tsv。这一层 SourcePack 主要是索 引视图，真实互相关 payload 仍在 ncf/xcpack/*.xcpack。

叠加和旋转之后的 SourcePack 则是实际物化后的结果。例如 stack/linearstack_sourcepack/STACK/linearstack.pack 里存放 linear stack 后 的新 trace，旁边的 sourcepack_index.tsv 记录每条 trace 在 pack 中的位置。 PWS 和 TF-PWS 也使用同样的 pack + index 结构，只是由于 GPU worker 并行，可能 会有多个 worker shard pack。

如果需要传统 SAC 文件，用默认开启的 unpack 阶段或手动运行 fastxc unpack 导出。也就是说，SAC 是输入格式和最终导出格式，而不是 FastXC 后半段的主要工 作格式。

旧的 BigSAC 拼接/抽取路径已经从当前主流程和工具入口中移除。当前推荐路径是 stepack -> xcpack -> SourcePack -> stack/rotate -> unpack；需要人工查看时， 先从 SourcePack 导出 SAC，或使用下面的工具直接检查 StepPack/结果 SAC。

常用手动工具见 工具命令。例如：

fastxc sac2dat -I /path/to/sac_dir -O /path/to/dat_dir
fastxc sourcepack -I /path/to/workspace/ncf -O /path/to/workspace/sourcepack
fastxc unpack -I /path/to/sourcepack_index.tsv -O /path/to/sac_dir
fastxc plot-rtz-grid -I /path/to/result_ncf/ncf_linear_RTZ --source A7K2
fastxc extract-stepack --workspace /path/to/workspace --timestamp 2023.001.0000 --station A7K2 -O A7K2.stepack.mat --plot

plot-rtz-grid 会自动识别单分量结果和三分量 3x3 结果：单分量输出一张子 图，RTZ/ENZ 这类九分量输出九宫格。extract-stepack --plot 会同时导出 .mat 和一张快速检查 PNG；已有 .mat 仍可用 fastxc plot-stepack-mat 重新绘图。

文档

更长的中文项目说明放在 docs_ZH/，英文说明放在 docs_EN/：

  • 配置说明：INI 字段、路径 pattern 和常见取值。
  • App 图文全参数说明书：真实截图、完整操作、质量门禁、全部 hover 参数和 91 小时 SmartSolo 实例结论。
  • 架构说明：数据流和模块边界。
  • 输出说明：各阶段输出目录和产物用途。
  • 工具命令：独立工具命令、手动导出、格式转换和调试用途。
  • 结果策略：公开仓库中的结果产物和本地输出保留策略。
  • English docs：英文文档入口。
  • Changelog：架构调整、兼容性变化和历史决策。

项目目录

fastxc/              Python 包、CLI、配置解析、调度控制
fastxc/inventory/    SAC inventory、源文件匹配、NSL ID、路径规划
fastxc/system/       可执行文件发现、日志配置、模板导出
fastxc/stages/       主流程阶段调度
fastxc/adapters/     原生可执行程序命令适配
fastxc/runtime/      原生子进程执行和进度轮询
fastxc/io/           SAC、SourcePack 等索引/数据格式读写
fastxc/operators/    Python 实现的 SourcePack、stacking、rotation、filter 算子
fastxc/resources/    内置配置模板和静态资源
native/sac2spec/     CUDA SAC2SPEC 后端
native/xc/           CUDA 互相关后端
native/pws/          CUDA PWS 后端
native/tfpws/        CUDA TF-PWS 后端
configs/             公开 smoke 配置
example/             内置示例：配置、匿名数据和绘图脚本
tools/               可选独立工具
docs_ZH/             中文架构和公开项目说明
docs_EN/             English architecture and public project notes

排错

检查 Python 配置和原生可执行文件发现情况：

fastxc doctor config.ini

查看原生构建配置：

make -C native print-config

迁移到新机器时，优先检查：

nvcc --version
nvidia-smi
make -C native print-config
fastxc doctor config.ini

作者与引用

如果你有问题、建议，或希望参与改进，欢迎在 GitHub Issues 中讨论。 更深入的问题也可以通过邮件联系作者： wkh16@mail.ustc.edu.cn。

如果 FastXC 对你的研究有帮助，欢迎引用下列 FastXC 方法论文：

Wang et al. (2025). High-performance CPU-GPU Heterogeneous Computing Method for 9-Component Ambient Noise Cross-correlation. Earthquake Research Advances.

声明与致谢

FastXC 最早由中国地震局地球物理研究所王伟涛老师团队委托中国科学技术大学 计算机学院李会民教授、网络信息中心孙广中老师和吴超老师团队开发；后续优化 与公开整理主要由作者继续完成。

感谢来自中国科学技术大学、中国地震局地球物理研究所、中国地震局预测所、 中国科学院地质与地球物理研究所的同事和朋友在测试、试运行和反馈中提供的 帮助。

本项目 v2605 公开整理、文档重写和发布打包过程使用了 OpenAI Codex / GPT Pro 辅助。早期 README 标题配图由 ChatGPT 生成。

参考文献

许可证

FastXC 使用 MIT License。详见 LICENSE。

About

High Performance Noise Cross-Corelation Computing Code for 9-component Recordings

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages