入门 操作指南
OGGM的命令行界面（CLI）是面向最终用户的主要交互接口。通过cli/目录下的一组模块，用户无需编写Python代码即可完成从数据下载到全球冰川模拟的完整工作流。本章详细解析CLI的架构设计、主要命令、配置机制和HPC部署模式。
OGGM使用PEP 621标准的pyproject.toml注册CLI入口点。每个CLI命令对应一个[project.scripts]条目：
[project.scripts] oggm_prepro = "oggm.cli.prepro_levels:main" oggm_benchmark = "oggm.cli.benchmark:main"
当用户执行oggm_prepro时，Python调用oggm.cli.prepro_levels.main()函数。这种设计遵循了Python打包的最佳实践，保证了跨平台的兼容性。
| 模块 | 命令 | 用途 |
|---|---|---|
prepro_levels.py | oggm_prepro | 主力常用预处理管线（L0-L5） |
benchmark.py | oggm_benchmark | 性能基准测试 |
oggm_prepro是OGGM最重要（也最复杂）的命令行工具。它将第15章讨论的5级预处理管线暴露为一系列命令行参数。
oggm_prepro \ --rgi-reg 01 \ # RGI区域编号 --rgi-version 6 \ # RGI版本 --map-border 160 \ # 周围边距（像素） --start-level 0 \ # 起始预处理级别（prepro level） --max-level 4 \ # 最大运行级别 --working-dir /path/to/wd \ # 工作目录 --output-dir /path/to/out # 输出目录
--start-level和--max-level定义了管线执行的起止范围。完整流程为L0→L1→L2→L3→L4→L5：
| 级别 | 执行内容 | 关键输出文件 |
|---|---|---|
| L0 | RGI初始化，gdir创建 | glacier_grid.json |
| L1 | DEM裁剪，冰川掩膜 | gridded_data.nc, glacier_mask.tif |
| L2 | 完整GIS预处理链 | centerlines.pkl, geometries.pkl |
| L3 | 气候数据+MB校准+反演 | inversion_output.pkl, climate_historical.nc |
| L4 | 历史模拟运行 | model_diagnostics.nc, model_flowlines.nc |
| L5 | 清理中间文件 | 仅保留最终输出 |
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--rgi-reg | str | OGGM_RGI_REG env | RGI区域编号（如"01"代表Alaska） |
--rgi-version | int | 6 | RGI版本（6或7） |
--map-border | int | 160 | 冰川周围扩展像素数（越大越"安全"但对DEM而言更贵） |
--start-level | int | 0 | 起始预处理级别（prepro level） |
--max-level | int | 5 | 最大运行级别 |
--start-base-url | str | None | 恢复归档的URL（增量重启） |
--working-dir | str | OGGM_WORKDIR env | 工作目录路径 |
--output-dir | str | OGGM_OUTDIR env | 输出目录路径（与workdir可分离） |
--dem-source | str | 配置默认 | DEM源（ALL, STANDARD, 或特定代码如"COPDEM"） |
--elev-bands | flag | False | 使用elevation bands流线方法（默认为中心线方法） |
--centerlines | flag | True | 使用中心线方法（默认启用） |
--mb-calibration-strategy | str | informed_threestep | MB校准策略：informed_threestep, melt_temp, temp_melt |
--add-consensus-thickness | flag | False | 添加Farinotti共识冰厚数据 |
--add-itslive-velocity | flag | False | 添加ITS_LIVE表面速度数据 |
--add-millan-thickness | flag | False | 添加Millan冰厚估计数据 |
--add-hugonnet-dhdt | flag | False | 添加Hugonnet高程变化率数据 |
--dynamic-spinup | str | None | 动态预热（dynamic spinup）策略（area/dmdtda, volume/dmdtda） |
--override-params | str | None | JSON字符串覆盖默认参数 |
OGGM提供两种流线提取方法，通过--elev-bands和--centerlines互斥标志选择：
--mb-calibration-strategy控制温度敏感度参数mu*的校准方式：
| 策略 | 算法 | 适用场景 |
|---|---|---|
informed_threestep | 三步信息校准（默认） | 标准正式运行，有大地测量MB数据 |
melt_temp | 融化温度法 | 简化校准，备选方案 |
temp_melt | 温度融化法 | 另一备选方案 |
OGGM CLI的参数解析遵循明确的优先级：
CLI显式参数 > 环境变量 > params.cfg配置文件 > 内置默认值
五个核心环境变量：
| 变量 | 作用 |
|---|---|
OGGM_RGI_REG | 默认RGI区域编号 |
OGGM_MAP_BORDER | 默认地图边距 |
OGGM_WORKDIR | 默认工作目录 |
OGGM_OUTDIR | 默认输出目录 |
OGGM_EXTRACT_DIR | 临时解压目录 |
复合参数通过--override-params传入JSON字符串覆盖params.cfg中的任意值：
oggm_prepro --override-params '{"mp_processes": 8, "use_multiple_flowlines": false}' \ ...
--override-params提供的JSON会与params.cfg进行浅层合并。嵌套配置项（如"climate": {"temp_use_gradient": true}）可能需要完整提供嵌套对象。建议在运行前用oggm.cfg.log_params()验证最终生效的参数。
--start-base-url是工业化生产的关键参数。它允许从远程URL加载前一个预处理级别（prepro level）的tar存档，实现断点恢复：
# 首次运行L0-L2 oggm_prepro --start-level 0 --max-level 2 ... # L2完成后，从L2存档恢复，继续L3-L5 oggm_prepro --start-level 3 --max-level 5 \ --start-base-url https://cluster.unibe.ch/prepro/RGIv6/L2/RGI01_L2.tar.gz ...
这种设计将耗时的工作流分解为可独立调度、可故障恢复的阶段。在SLURM集群中，每个级别可以提交为独立的job array，充分利用作业调度系统的容错能力。
cli/benchmark.py提供了一个标准化的性能测试工具。它定义了一条13任务的线性管线，在恒定气候和随机气候两种条件下各运行250年：
benchmark_tasks = [
tasks.define_glacier_region,
tasks.glacier_masks,
tasks.compute_centerlines,
tasks.initialize_flowlines,
tasks.compute_downstream_line,
tasks.compute_downstream_bedshape,
tasks.catchment_area,
tasks.catchment_intersections,
tasks.catchment_width_geom,
tasks.catchment_width_correction,
tasks.process_climate_data,
tasks.local_mustar,
tasks.run_random_climate, # 或 run_constant_climate
]
对每个任务，benchmark记录执行时间并输出CSV格式的计时报告。constant_climate模式使用不变的气候（适合测试模型物理），random_climate模式使用随机生成的气候序列（适合测试模型对气候变率的响应）。
RGI的19个一级区域天然适合SLURM job array：
#!/bin/bash #SBATCH --job-name=oggm_prepro #SBATCH --array=1-19 #SBATCH --ntasks=1 #SBATCH --cpus-per-task=16 export OGGM_WORKDIR=/scratch/oggm_work export OGGM_OUTDIR=/scratch/oggm_output oggm_prepro \ --rgi-reg $(printf "%02d" $SLURM_ARRAY_TASK_ID) \ --start-level 0 \ --max-level 5
每个数组任务处理一个RGI区域，16个CPU核心用于multiprocessing。19个任务可以并行提交（取决于集群资源限制），总吞吐量受限于最慢的区域（通常是区域19，南极外围冰川）。
对于单个大型RGI区域（如Alaska有超过27000条冰川），单节点16核可能不够。此时可以启用MPI跨节点并行：
#!/bin/bash #SBATCH --job-name=oggm_mpi #SBATCH --nodes=4 #SBATCH --ntasks-per-node=16 mpirun -np 64 python -c " from oggm import workflow # ... 设置RGI区域 ... workflow.execute_entity_task(task, gdirs) "
# 仅处理RGI60-11.00897（Hintereisferner） oggm_prepro \ --rgi-reg single \ --start-level 0 --max-level 5 \ --working-dir ./test_wd
oggm_prepro \ --rgi-reg 01 --rgi-version 6 \ --map-border 160 \ --dem-source COP30 \ --start-level 0 --max-level 4
oggm_prepro \ --rgi-reg 11 --rgi-version 6 \ --dynamic-spinup volume/dmdtda \ --start-level 3 --max-level 4 \ --add-consensus-thickness
for reg in 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19; do oggm_prepro --rgi-reg $reg --start-level 0 --max-level 5 & done wait
OGGM的CLI层将强大的科学计算能力封装为直观的命令行参数。从简单的单冰川测试到全球19个区域的分布式处理，oggm_prepro提供了统一的界面。理解其参数体系、环境变量优先规则和增量恢复机制，是在HPC环境中高效使用OGGM的前提。