Focus

Focus 是一个高性能的命令行地震震源反演框架，专为超级计算环境设计。它提供了与 Grond 相当的核心能力，同时使用 C++ 实现所有计算密集型算法，并使用 OpenMP 进行节点内并行化。

Grond 对齐状态：Focus 在真实数据上通过了一对一验证（GFZ 2020zocb 克罗地亚 M6.4：全局 misfit 1.00 vs Grond 0.99；Ridgecrest 2019 M7.1 GNSS：最佳 strike 136.3° vs 目录 137.2°）。 频域积分对齐：使用 transfer()/remove_response() 内置频域 1/(iω)ⁿ 积分，与 Pyrocko/Grond quantity=displacement 等价（commit c9e43eb）。 aarch64 跨平台一致：在天河新一代超算（NSCC HNU, mt_module 16 核节点）通过 Tier-1 端到端验证——bench_quick 在 synth_ahfull 自一致数据上 aarch64 与 x86_64 产生完全相同的结果（commit 9e0a8b4）。详见 docs/next_steps.md 与 docs/tianhe_validation_runbook.md。

功能特性

• 矩张量 (MT) 和双力偶 (DC) 反演
  • full_mt、deviatoric、double_couple、vlvd 参数化
  • dc_mt 参数化：Grond 风格的在 MT 分量空间中搜索 DC，使用 preconstrain 投影，推荐用于全球 DC 反演
  • cmt_deviatoric：12 参数 CMT，包含 time / north_shift / east_shift 和半正弦 STF
  • MT 分解为 DC / CLVD / ISO 百分比
  • 震源模型从配置中的 problem_type 选择
• 矩形（有限断层）震源模型，用于 InSAR/GNSS 联合反演
  • 9 个参数：length, width, strike, dip, rake, slip, depth, east_shift, north_shift
  • Okada 位错正演模型
• 基于物理的地震正演模型：从基本格林函数（Herrmann / Jost & Herrmann 1989） 合成矩张量辐射模式，适用于 Z/R/T 分量
• 频域积分：transfer(output_units="M") 在同一 FFT 内完成 响应去除 + 带通 + 1/(iω)ⁿ 积分，与 Pyrocko/Grond quantity=displacement 等价
• 内置解析 GF 存储和 Pyrocko/Fomosto 原生 GF 存储读取器， 使用 pyrocko 的 elastic10 矩张量合成——已通过 pyrocko 逐位精度验证 （max rel 8.9e-7）。线程安全的 LRU 波形缓存。
• 仪器响应去除，通过 StationXML 零极点的频谱反卷积实现， 与 pyrocko 的传递函数匹配
• Grond 风格的 raw+responses 管线：StationXML 目录合并、逐分量 响应去除、ENZ 通道方位角投影、RTZ 旋转（rotate_raw_to_rtz）
• 震源时间函数：impulse / boxcar / triangular / half_sine
• 多域波形 misfit：时间域 / 频率域 / 对数频率域 / 包络 / 绝对值 / cc_max_norm
• Grond 风格的 TargetBalancingAnalyser：随机震源合成能量平衡，按族归一化
• 贝叶斯和经典 bootstrap 权重与残差
• HighScore / BABO 优化器，具有均匀 → 定向 → 收敛三个阶段
• 差分进化优化器（备用方案）
• InSAR / GNSS 目标，支持完整协方差矩阵（马氏距离）
• HDF5 / NetCDF-4 结果输出，Markdown + HTML 报告含波形拟合和收敛图
• OpenMP 并行和 MPI 分布式 bootstrap
• 天河新一代 SLURM 部署：完整 scripts/tianhe/ 作业脚本（9 个 yhbatch 脚本，mt_module 优先 + ft_module 自动回退的智能 submit.sh）
• 命令行驱动的工作流：init、check、go、forward、harvest、evaluate、export、response、mt、report、version

构建

本机 / 通用 Linux

mkdir build && cd build
cmake .. -DFOCUS_ENABLE_OPENMP=ON -DFOCUS_BUILD_TESTS=ON
make -j

天河新一代超算（NSCC HNU, aarch64）

重要：天河 登录节点禁止运行可执行文件，仅允许编译与作业提交。 完整使用规则见 docs/tianhe_usage.md；本节给出最小工作流。

# 登录
ssh hnu_wuq@25.8.100.22

# 一次性：rsync 上传源码（仓库根对应 ~/focus_src/）
rsync -avP --exclude '.git' --exclude 'build/' \
    /local/path/focus/ hnu_wuq@25.8.100.22:~/focus_src/

# 在登录节点构建（启用 aarch64 原生 flags；前提 login node CPU 有 crypto 扩展）
cd ~/focus_src
bash scripts/tianhe/build.sh --aarch64     # Release + tests + armv8.2-a+neoverse-n1
bash scripts/tianhe/build.sh --aarch64 --mpi    # 启用 MPI
bash scripts/tianhe/build.sh --aarch64 --clean  # 重新构建

# 在登录节点提交作业到计算节点（登录节点禁止跑 focus）
# 推荐：智能包装 (mt_module 优先，失败回退 ft_module)
bash scripts/tianhe/submit.sh scripts/tianhe/smoke_test.sh                  # ctest 单测
bash scripts/tianhe/submit.sh scripts/tianhe/regr_smoke.sh                  # 7 MB 端到端
bash scripts/tianhe/submit.sh scripts/tianhe/verify_aarch64_reference.sh    # Pyrocko GF 容差回归
bash scripts/tianhe/submit.sh scripts/tianhe/bench_quick.sh                 # quick 反演
# 也可直接 yhbatch（仅主分区，不回退）：
# yhbatch scripts/tianhe/smoke_test.sh
yhqueue -u $USER
yhcancel <JOBID>

分区优先级：mt_module（16 核/节点，10240 个，idle 多）→ 回退 ft_module（64 核/节点，1024 个，排队更频繁）。详见 docs/tianhe_usage.md §4.1 与 scripts/tianhe/README.md。

Tier-1 验证（commit 9e0a8b4）：在天河上 build → smoke_test → verify_aarch64_reference → bench_quick 端到端跑通；并通过 scripts/tianhe/setup_synth_ahfull_bench.py 生成自一致 synth 数据，aarch64 与 x86_64 在 bench_quick 产生完全相同的恢复结果（Kagan / Mw / depth 三项完全一致）。完整步骤见 docs/tianhe_validation_runbook.md。

也可直接通过根目录下的 quick_bench.sh/full_bench.sh 等薄包装脚本提交到天河； 所有根目录 *_bench.sh 会自动检测 yhbatch 是否可用并转交。

构建

本机 / 通用 Linux

mkdir build && cd build
cmake .. -DFOCUS_ENABLE_OPENMP=ON -DFOCUS_BUILD_TESTS=ON
make -j

天河新一代超算（NSCC HNU, aarch64）

重要：天河 登录节点禁止运行可执行文件，仅允许编译与作业提交。 完整使用规则见 docs/tianhe_usage.md；本节给出最小工作流。

# 登录
ssh hnu_wuq@25.8.100.22

# 一次性：rsync 上传源码（仓库根对应 ~/focus_src/）
rsync -avP --exclude '.git' --exclude 'build/' \
    /local/path/focus/ hnu_wuq@25.8.100.22:~/focus_src/

# 在登录节点构建（含 aarch64 原生 flags）
cd ~/focus_src
bash scripts/tianhe/build.sh --aarch64     # Release + tests + armv8.2-a+neoverse-n1
bash scripts/tianhe/build.sh --aarch64 --mpi    # 启用 MPI
bash scripts/tianhe/build.sh --aarch64 --clean  # 重新构建

# 在登录节点提交作业到计算节点（登录节点禁止跑 focus）
# 推荐：智能包装 (mt_module 优先，失败回退 ft_module)
bash scripts/tianhe/submit.sh scripts/tianhe/smoke_test.sh                  # ctest 单测
bash scripts/tianhe/submit.sh scripts/tianhe/regr_smoke.sh                  # 7 MB 端到端
bash scripts/tianhe/submit.sh scripts/tianhe/verify_aarch64_reference.sh    # Pyrocko GF 容差回归
bash scripts/tianhe/submit.sh scripts/tianhe/bench_quick.sh                 # quick 反演
# 也可直接 yhbatch（仅主分区，不回退）：
# yhbatch scripts/tianhe/smoke_test.sh
yhqueue -u $USER
yhcancel <JOBID>

分区优先级：mt_module（16 核/节点，10240 个，idle 多）→ 回退 ft_module（64 核/节点，1024 个，排队更频繁）。详见 docs/tianhe_usage.md §4.1 与 scripts/tianhe/README.md。

也可直接通过根目录下的 quick_bench.sh/full_bench.sh 等薄包装脚本提交到天河； 所有根目录 *_bench.sh 会自动检测 yhbatch 是否可用并转交。

可选依赖（如找到将自动使用）：

# Ubuntu / Debian
sudo apt-get install libhdf5-dev libyaml-cpp-dev libfftw3-dev libnetcdf-c++4-dev libmseed-dev catch2

Python 工具（tools/benchmark_focus.py、tools/focus_report.py）需要：

pip install h5py pyrocko matplotlib jinja2

运行 CLI：

# 使用模板配置创建项目骨架
./apps/focus init my_project

# 从 'forward' 震源生成合成波形（内置解析 GF 存储）
./apps/focus forward my_project/config.yaml

# 将其作为观测数据输入并进行反演
cp my_project/runs/forward/*.sac my_project/data/waveforms/
./apps/focus check my_project/config.yaml
./apps/focus go    my_project/config.yaml

# 或运行内置示例
./apps/focus check ../data/example_config.yaml
./apps/focus go    ../data/example_highscore_config.yaml

运行测试：

# 本机
./tests/focus-tests

# 天河（通过 SLURM 提交）
cd ~/focus_src
yhbatch scripts/tianhe/smoke_test.sh

项目结构

├── apps/              # 命令行应用程序 (focus-cli)
├── include/focus/     # 公共 C++ 头文件
├── src/core/          # 核心库：模型、问题、优化器、分析
├── src/gf/            # 格林函数引擎 (Pyrocko, HDF5, Okada, SPTree)
├── src/io/            # 数据 I/O (SAC, MiniSEED, StationXML, HDF5, NetCDF, harvest)
├── tests/             # 单元测试 (Catch2, 72 个测试用例 / x86_64;  68/68 在天河跳过 4 个缺依赖项)
├── tools/             # Python 脚本（基准测试、报告、数据生成、synth_ahfull）
├── scripts/tianhe/    # 天河 (NSCC HNU) SLURM 作业脚本（9 个 yhbatch 脚本 + submit.sh）
├── data/              # 示例配置
├── docs/              # 设计文档、Grond 对齐计划和路线图（含 tianhe_usage.md）
└── CMakeLists.txt     # CMake 构建 (C++17, OpenMP, 可选 MPI)

验证结果

目标平台	环境	ctest	bench_quick (synth_ahfull)	构建
x86_64（本地）	g++ 13.3, Ubuntu 24.04	72/72 ✅	recov s/d/r/Mw/depth (42)	HDF5 + libmseed + NetCDF + Catch2
aarch64（天河 NSCC HNU mt_module）	g++ 9.4, Ubuntu 20.04	68/68 ✅	与 x86_64 完全一致	yaml-cpp + libxml2 + Catch2（无 HDF5/libmseed/NetCDF，跳过 4 个测试）

Tier-1 aarch64 跨平台验证详情（commit 9e0a8b4）：synth_ahfull 自一致数据 （tools/setup_synth_ahfull_bench.py 用 focus forward 生成）上， bench_quick seed 42 恢复结果在 aarch64 mt_module 16 核与 x86_64 上完全相同 （recovered strike=36.2, dip=44.7, rake=-153.2, Mw=5.376, depth=4946 m）。 Kagan 距离 95.18° 是数据驱动（粗略合成的 Ricker 高斯 vs 真实弹性波场）， 非平台问题——见 ~/grond_benchmark/data/aarch64_reference/synth_ahfull_kagan.md 的详细分析与 docs/replace_grond_plan.md §Phase 1。

路线图与下一步工作

详见 docs/roadmap.md（功能对账，✅/⏳ 状态）、 docs/replace_grond_plan.md（4 阶段 实施）和 docs/next_steps.md（当前快照的执行 优先级）：

• Tier 1（✅ 完成）：天河 aarch64 端到端验证 — build + ctest + verify_aarch64_reference + 5 步 end-to-end 通过 Tier-1 runbook
• Tier 2：Phase 1 收尾 — 原生 TargetBalancingAnalyser、bootstrap 权重、per-target m/n 分析
• Tier 3：Phase 2 功能补齐 — NoiseAnalyser、InSAR 协方差启用、RectangularSource、Hudson plot
• Tier 4：Grond 完全兼容 — grond-import、Grond 结果导出、DoubleDCSource、VolumePointSource

路线图与下一步工作

详见 docs/roadmap.md（功能对账，✅/⏳ 状态）、 docs/replace_grond_plan.md（4 阶段 实施）和 docs/next_steps.md（当前快照的执行 优先级：Tier 1 天河 aarch64 验证 → Tier 2 Phase 1 收尾 → Tier 3 Phase 2 功能补齐 → Tier 4 Grond 完全兼容）。

从 Grond 移植的关键 C++ 模块

模块	文件
矩张量波形合成	core/mt_synthesis.*（基本格林函数）
震源时间函数	core/stf.*
震源模型工厂 (problem_type)	core/source_model.*
解析 GF 存储	core/gf_store.* (InMemoryGFStore)
波形 misfit（多域）	core/waveform_misfit.*, core/trace.*
全局 misfit 组合	core/problem.*
Bootstrap 权重 / 残差	core/bootstrap_weights.*, core/bootstrap.*, core/bootstrap_analysis.*
HighScore / BABO 优化器	core/highscore_optimiser.*, core/chains.*
模型历史	core/model_history.*
矩张量分解	core/moment_tensor.*
InSAR / GNSS 静态 GF	gf/okada.*, gf/projection.*, gf/quadtree.*, core/satellite_target.*, core/gnss_target.*
目标噪声分析	core/target_analyser.*
SAC I/O	io/sac_io.*
结果输出 / 报告	io/result_writer.*

许可证

本项目基于 GNU General Public License v3.0 或更高版本许可。 详见 LICENSE。