第2章 架构总览与设计哲学

理解一个复杂科学软件的架构，是深入源码阅读的前提。OGGM的代码库约含10万行Python代码，分布在数十个模块中。本章从宏观层面解构OGGM的架构设计，重点分析其核心设计模式——特别是@entity_task和@global_task装饰器——以及数据如何在各模块间流动。

2.1 高层架构图

下图展示了OGGM的主要模块及其依赖关系。箭头表示"依赖/导入"方向（A ← B 表示 B 导入 A）：

                      ┌─────────────────────────────────────┐
                      │         oggm.cli / oggm.sandbox      │
                      │         (用户界面 & 实验代码)          │
                      └──────┬──────────────┬───────────────┘
                             │              │
                      ┌──────▼──────────────▼───────────────┐
                      │         oggm.workflow                │
                      │   (预定义处理工作流: init_glacier_    │
                      │    regions → gis_prepro → climate_   │
                      │    historical → inversion →           │
                      │    evolution_run)                     │
                      └──────┬──────────────┬───────────────┘
                             │              │
           ┌─────────────────▼──┐    ┌─────▼─────────────────┐
           │   oggm.core        │    │   oggm.shop            │
           │  ┌───────────────┐ │    │  ┌───────────────────┐ │
           │  │ gis           │ │    │  │ bedmachine        │ │
           │  │ centerlines   │ │    │  │ rgitopo           │ │
           │  │ climate       │ │    │  │ ecowitt           │ │
           │  │ massbalance   │ │    │  │ ...               │ │
           │  │ inversion     │ │    │  └───────────────────┘ │
           │  │ flowline      │ │    └────────────────────────┘
           │  │ dynamics      │ │
           │  └───────────────┘ │
           └────────┬───────────┘
                    │
           ┌────────▼───────────┐
           │   oggm.utils       │
           │  ┌───────────────┐ │
           │  │ _workflow     │ │ ← entity_task / global_task 装饰器
           │  │ _funcs        │ │ ← 栅格/几何工具函数
           │  │ g2ti          │ │ ← GlacierDirectory 类
           │  │ (gdir.py)     │ │
           │  └───────────────┘ │
           └────────┬───────────┘
                    │
           ┌────────▼───────────┐
           │   oggm.cfg         │
           │  ┌───────────────┐ │
           │  │ PARAMS        │ │ ← 参数配置
           │  │ PATHS         │ │ ← 路径管理
           │  │ BASENAMES     │ │ ← 文件名映射
           │  │ initialize()  │ │ ← 系统初始化
           │  └───────────────┘ │
           └────────────────────┘

可以看到，依赖关系遵循清晰的分层结构：cfg（配置层）是最底层；utils（工具层）依赖它；core（核心算法）和shop（扩展模块）依赖utils；workflow（工作流层）编排core中的任务；cli和sandbox则位于最上层，面向最终用户。

2.2 entity_task 装饰器：OGGM的核心设计模式

@entity_task 是OGGM架构中最关键的抽象。它位于 oggm/utils/_workflow.py 第422至530行，是一个Python装饰器，将普通函数包装为可处理单一冰川实体的"任务"。其核心代码签名如下：

def entity_task(task_func, *, writes_output=None, base_version=None,
                  log_level='INFO', ignore_errors=False, operation='entity_task'):
    # 包装器实现（约100行）
    def deco(task_function):
        # 1. 提取任务名称（函数名）
        # 2. 设置 base_version 用于版本兼容性检查
        # 3. 包装为 _entity_task_wrapper
        return new_func
    return deco

当一个函数被 @entity_task 装饰后，它自动获得以下能力：

1. 自动跳过（Auto-skip）：如果任务的所有输出文件都已存在且未过期，任务自动跳过。这由 _entity_task_wrapper 中的 _auto_skip_task() 函数实现（_workflow.py:340-420）。检查逻辑是：遍历任务通过 writes_output 或 @task_output 声明的输出文件列表，如果全部存在则跳过执行。
2. 日志记录：每次任务执行的时间戳、持续时间、成功/失败状态自动写入GlacierDirectory的 task_status.json 日志文件。如果任务失败，完整的traceback也会被记录。
3. 错误处理：支持 ignore_errors=True 模式（默认），即任务失败时不抛出异常，而是记录错误日志并标记任务状态为失败，让后续任务继续处理其他冰川。也支持 ignore_errors=False 模式，失败时立即终止。
4. 超时控制：通过 mp_pool_timeout_task 参数，可以为每个任务设置最大运行时间（以秒为单位），防止个别异常冰川长时间占用计算资源。
5. 版本兼容性：base_version 机制确保旧版本代码不会处理新版本代码创建的预处理器数据，避免难以调试的隐蔽错误。

典型使用模式（以 gis_prepro_tasks 中的 compute_centerlines 为例）：

@entity_task(log, writes_output=['centerlines', 'glacier_grid',
                          'hypsometry'])
def compute_centerlines(gdir, div_id=0, min_m=None,
                         single_fl=None, **kwargs):
    # 函数体内只需关注冰川物理逻辑
    # 跳过、日志、错误处理全部由装饰器负责
    ...

2.3 global_task 装饰器

@global_task（位于 _workflow.py 第533-566行）是 @entity_task 的"全局"变体。它用于处理不针对单一冰川的全系统操作，例如：

• 编译所有冰川的物质平衡统计信息
• 生成全局的交叉验证汇总表
• 创建区域汇总的shapefile

与 entity_task 不同的是，global_task 的签名不要求 gdir 作为第一个参数，且其自动跳过逻辑基于单个全局日志文件而非每个冰川的任务状态。其实现更为简单，约30行代码。

def global_task(log, task_func=None, *, operation='global_task',
                  writes_output=None):
    # 简化版 entity_task：
    # - 不绑定 gdir
    # - 跳过逻辑基于 writes_output 中的文件是否存在
    # - 日志写入全局文件（而非 per-gdir）
    ...

2.4 核心设计原则

OGGM的设计遵循以下四条核心原则，理解它们有助于把握源码中的各种约定：

2.4.1 基于实体的处理（Entity-based Processing）

OGGM的基本处理单元是"冰川"（glacier entity），每个冰川有一个独立的GlacierDirectory，存储其所有中间数据和模型输出。这种设计使得处理高度可并行：不同冰川之间没有数据依赖，可以独立地在不同CPU核心或不同计算节点上处理。这通过 @entity_task 和 utils._workflow.execute_entity_task() 实现。

2.4.2 配置驱动行为（Configuration-driven Behavior）

OGGM中几乎所有数值参数和路径设置都由 oggm.cfg.PARAMS 字典控制（参见第3章）。这意味着绝大多数行为变更不需要修改源码——只需修改 params.cfg 文件或通过环境变量覆盖。例如，将融化因子 melt_f 从默认值5.0改为3.0，即可全局转换所有物质平衡计算。

2.4.3 名称间接寻址（Filename Indirection）

代码中从不直接使用硬编码的文件名（如 'model_geometry.nc'），而是通过 BASENAMES 字典进行逻辑名称到物理名称的映射。这个设计使得 filesuffix 机制成为可能——通过添加后缀（如 '_rcp85', '_rcp26'），同一冰川在同一工作目录下可以运行多个气候情景的模拟而互不干扰（详见第4章）。

2.4.4 功能分区（Separation of Concerns）

core/ 目录下的每个模块负责一个单一的科学领域（中心线、气候、物质平衡、反演、动力学），彼此之间通过GlacierDirectory中的文件进行数据交换，而非直接函数调用。这使得：

• 模块可以独立测试和替换
• shop/ 中的扩展模块可以无缝接入数据管道
• 新模型的集成只需确保输出文件格式与下游兼容即可

2.5 数据流：从RGI到冰川演化预测

OGGM的核心数据流遵循以下管线（pipeline）：

RGI轮廓 (shapefile)
    │
    ▼
[Step 1: gis_prepro]─── 从DEM提取冰川地形
    │                     输出: glacier_grid.json, dem_source.json,
    │                           hypsometry.csv, centerlines.pkl
    ▼
[Step 2: climate]────── 为每条冰川插入气候时间序列
    │                     输出: climate_historical.nc, gcm_data.nc
    ▼
[Step 3: massbalance]── 基于气候计算历史物质平衡
    │                     输出: ref_tstars.csv, local_mustar.json
    ▼
[Step 4: inversion]──── 反演冰厚度分布
    │                     输出: inversion_output.pkl,
    │                           inversion_flowlines.pkl
    ▼
[Step 5: dynamics]───── 运行冰动力演化模型
    │                     输出: model_geometry.nc,
    │                           model_diagnostics.nc
    ▼
最终输出: 冰川体积/面积/长度时间序列

关键点：每一步的输出文件是下一步的输入。这种基于文件的耦合（而非基于函数调用的耦合）是OGGM能够实现大规模并行处理的基础——每个步骤的代码只需要读取上一阶段产生的文件，不需要持有上一阶段的内存对象。

2.6 两种处理模式

OGGM支持两种冰川几何表示模式：

2.7 GlacierDirectory：数据中枢预览

GlacierDirectory（定义于 oggm/utils/g2ti.py 或更早的 oggm/utils/_workflow.py，约第2643-3960行，共约1300行）是OGGM架构中核心的数据结构。它充当每条冰川的"数据中枢"，管理着：

• 目录结构：冰川的所有文件存储在 base_dir/RGIID[:8]/RGIID[:11]/RGIID/ 路径下（例如 per_glacier/RGI60-11/00/RGI60-11.00001/）
• 文件读写：提供统一的方法读写pickle、shapefile、JSON和NetCDF文件，所有路径都经由 BASENAMES 间接解析
• 任务日志：维护 task_status.json，记录每个entity_task的执行时间、状态和错误日志
• 参考数据缓存：气候参考数据通过 set_ref_mb_data() 和 get_ref_mb_data() 方法进行延迟加载

GlacierDirectory的详细剖析见第4章。

2.8 冰川目录（GlacierDirectory）中的文件组织

一个完全处理后的冰川目录（GlacierDirectory）包含以下典型文件：

per_glacier/RGI60-11/00/RGI60-11.00001/
    ├── glacier_grid.json          # 本地网格定义
    ├── dem_source.json            # DEM数据源信息
    ├── centerlines.pkl            # 计算的流线 (shapely geometries)
    ├── downstream_line.pkl        # 下游线（downstream line）几何
    ├── flowline_catchments.pkl    # 流线集水区
    ├── hypsometry.csv             # 面积-高程分布表
    ├── climate_historical.nc      # 历史气候时间序列 (NetCDF)
    ├── gcm_data.nc                # GCM偏移气候数据
    ├── local_mustar.json          # 校准后的温度敏感性
    ├── ref_tstars.csv             # 参考温度偏差
    ├── inversion_input.pkl        # 反演参数
    ├── inversion_flowlines.pkl    # 包含厚度的反演后流线
    ├── inversion_output.pkl       # 反演输出完整对象
    ├── model_geometry.nc          # 模型几何时间序列
    ├── model_diagnostics.nc       # 模型诊断变量时间序列
    └── task_status.json           # 任务执行日志

2.9 包结构总览

2.10 模块间的依赖关系图

以下为更精确的模块级DAG（有向无环图）：

cfg.py                    # 零依赖（仅依赖标准库 + configobj）
  ├── _workflow.py        # 依赖 cfg
  │     ├── g2ti.py       # 依赖 _workflow, cfg
  │     └── _funcs.py     # 依赖 cfg
  ├── core/gis.py         # 依赖 utils._funcs, g2ti, _workflow
  ├── core/centerlines.py # 依赖 gis, _funcs, _workflow
  ├── core/climate.py     # 依赖 gis, _funcs, _workflow
  ├── core/massbalance.py # 依赖 climate, _funcs, _workflow
  ├── core/inversion.py   # 依赖 massbalance, flowline, _workflow
  ├── core/flowline.py    # 依赖 massbalance, _funcs, _workflow
  ├── core/dynamics.py    # 依赖 flowline, _workflow
  └── shop/*              # 依赖 core/*, utils/* —— 但从不被core依赖

这种单向、无循环的依赖结构使得OGGM的模块可以独立开发和测试。特别值得注意的是，shop/ 中的模块可以依赖 core/ 和 utils/，但反过来不行——这确保了核心代码的稳定性不受扩展模块变化的影响。