Coupling ISSM and CUAS-MPI: example cases

Coupling of ISSM and CUAS-MPI with preCICE: Sample Cases

This data set contains samples cases for coupling of the Ice-sheet and Sea-level System Model (ISSM) with subglacial hydrology model CUAS-MPI, an MPI-parallel implementation of the Confined-Unconfined Aquifer System model. The coupling is performed by the coupling library preCICE. ISSM computes the state of the ice sheet (e.g., ice thickness, ice velocity, melting rates) and CUAS-MPI computes the effective water pressure that is included in the sliding law used by ISSM.

Thule: A synthetic ice sheet, based on the Thule geometry developed for the CalvingMIP (https://github.com/JRowanJordan/CalvingMIP/wiki/) project. The sample can be run either fully coupling or one directional coupling. The sample is a simple demonstration of the capabilities of the adapters and demonstrates the effects of the feedback. The algorithmically generated geometry is just complex enough to see effects of coupling in areas of grounded and floating ice and at the margins between these areas. The setups were generated by simulating uncoupled in ISSM with the built-in effective pressure until the ice reaches steady state, then spinning up (also without coupling) a consistent hydrology based on the steady state geometry.

Greenland: A medium resolution model of the Greenland Ice Sheet based on setups G1000 from Fischler et al. (2022, doi 10.5194/gmd-15-3753-2022) and G600 from Fischler et al. (2023, doi 10.5194/gmd-16-5305-2023). These setups are not entirely consistent, so the simulation result is not realistic. The sample is mostly intended to produce representative performance measurements, enabling comparison of parallel and serial coupling (see below.)

Requirements

To run the cases, the following software is required (does not include transitive dependencies):- ISSM 4.24 (website)- preCICE 3.0 or higher (website)- ISSM-preCICE adapter 0.4 (gitlab, zenodo)- CUAS-MPI 0.1 with preCICE adapter (zenodo)

Installation instructions can be found in the referenced websites and source code archives.

Run Coupled Simulations

Sample cases include scripts to run the setups on a high-performance computing cluster. The scripts are specific for the Albedo cluster hosted by the Alfred Wegener Institute Helmholtz Center for Polar and Marine Research, but should run on other clusters with minor adaptations, including but not limited to:- Filesystem paths in queue_job.sh- Environment setup for participants in env.sh files (e.g. load modules)- Slurm directives for accounts, partitions, etc. in `queue_job.sh`- Replace srun with mpirun or any other equivalent command required by the cluster

To run the coupled setups, there is a queue_job.sh script in both greenland/coupled, thule/1way, and thule/2way directories. First edit the configuration in queue_job.sh (parallel or serial coupling, directories, slurm settings, etc)Then execute the script to queue a SLURM job.

Spin-ups

Both setups also contain spin-up directories to create the coupled setup data files from scratch.

Greenland 

Both spin-ups are run independently.

- ISSM spin-up: provided without data files, see Fischler et al. (2022, doi 10.5194/gmd-15-3753-2022) for the full setup and compare to see changes made for coupling.- CUAS spin-up: not included, see Fischler et al. (2023, doi 10.5194/gmd-16-5305-2023)

Thule

Process:1. run uncoupled ISSM spin-up2. export data files for CUAS spin-up: ISSM restart, initial CUAS input3. run CUAS spin-up coupled to ISSM4. export data files for coupling: ISSM and CUAS restart, seasonal forcing

Postprocessing 

Greenland

This case is used for analyzing computational performance. Experiment directory names follow the schema work-<coupling scheme>-<ISSM CPUs>-<CUAS CPUs>-<date>-<time>. For the profiling runs, builds of ISSM and CUAS-MPI were used that don't write any output, since variance of IO on the cluster is too high (modify the solver/adapter configs to produce output for diagnostics or other). Otherwise, the shell script were used as explained above. Profiling is enabled in the included config files.

The provided scripts were used to analyze the raw and aggregated profile data:- analyze.sh: use `precice-profiling` tools included in the preCICE distribution to extract profiles and traces from the raw data.- aggregate.py: load traces of on or more runs and compute statistics (e.g., averages over runs, tasks, and coupling windows).- plot_*.py: plot different aspects of performance results (scaling, mapping comparisons)- archive.sh: compress experiment directories into an archive.

Thule

This case is used to demonstrate functionality. Postprocessing steps:

- post-processing.sh: generate derived variables from output of 1way and 2way coupling simulations    - 1way coupling files do not contain the correct basal_velocity_ice fields, because they are not coupled    - same units dissagree (fix in post-processing)    - spatial averaging    - (optional) check results using CDO- plot_*: plot map and time series of results

基于preCICE的ISSM与CUAS-MPI耦合示例案例

本数据集包含冰盖与海平面系统模型（Ice-sheet and Sea-level System Model, ISSM）与冰下水文模型CUAS-MPI的耦合示例案例，其中CUAS-MPI是受限-非受限含水层系统模型（Confined-Unconfined Aquifer System model）的MPI并行实现。该耦合通过耦合库preCICE实现。ISSM用于计算冰盖状态（如冰厚度、冰流速、消融速率等），CUAS-MPI则负责计算ISSM滑动律所使用的有效水压力。

### Thule
Thule：基于CalvingMIP项目开发的Thule几何结构构建的合成冰盖。本示例支持全耦合与单向耦合两种运行模式，旨在直观展示适配器的功能与耦合反馈效应。该算法生成的几何结构复杂度适中，可清晰观测接地冰、浮冰以及二者交界区域的耦合效应。本配置的生成流程为：首先在ISSM中运行非耦合模拟，使用内置有效压力模块直至冰盖达到稳态；随后基于该稳态几何结构启动非耦合水文模块的自旋初始化过程，以构建一致的初始水文状态。

### Greenland
Greenland：基于Fischler等人（2022年，DOI: 10.5194/gmd-15-3753-2022）提出的G1000配置，以及Fischler等人（2023年，DOI: 10.5194/gmd-16-5305-2023）提出的G600配置构建的中分辨率格陵兰冰盖模型。由于这两套配置并非完全一致，因此模拟结果不具备现实性。本示例主要用于生成具有代表性的性能测试数据，支持并行耦合与串行耦合的对比分析（详见下文）。

## 运行要求
运行本案例所需软件如下（不包含传递依赖）：
- ISSM 4.24（官方网站）
- preCICE 3.0及以上版本（官方网站）
- ISSM-preCICE适配器0.4（GitLab、Zenodo平台）
- 搭载preCICE适配器的CUAS-MPI 0.1（Zenodo平台）

安装说明可参考对应官方网站与源代码归档文件。

## 耦合模拟运行指南
示例案例包含用于在高性能计算集群上运行配置的脚本。这些脚本专为阿尔弗雷德·魏格纳研究所亥姆霍兹极地与海洋研究中心托管的Albedo集群编写，但稍加适配后即可在其他集群运行，适配内容包括但不限于：
- 修改queue_job.sh中的文件系统路径
- 调整env.sh文件中的环境配置（如加载模块）
- 修改queue_job.sh中针对账户、分区等的Slurm作业指令
- 将srun替换为集群所需的mpirun或其他等效命令

运行耦合配置的脚本分别位于greenland/coupled、thule/1way以及thule/2way目录下的queue_job.sh文件。首先需编辑该脚本的配置项（包括并行/串行耦合模式、目录路径、Slurm设置等），随后执行该脚本以提交SLURM作业。

## 自旋初始化流程
两套配置均包含自旋初始化目录，用于从零开始构建耦合配置所需的数据文件。

#### Greenland
两个自旋初始化过程需独立运行：
- ISSM自旋初始化：未附带数据文件，完整配置详见Fischler等人（2022年，DOI: 10.5194/gmd-15-3753-2022），可通过对比验证耦合修改内容。
- CUAS自旋初始化：未包含在内，详见Fischler等人（2023年，DOI: 10.5194/gmd-16-5305-2023）

#### Thule
处理流程：
1. 运行非耦合ISSM自旋初始化
2. 导出CUAS自旋初始化所需的数据文件：ISSM重启文件、CUAS初始输入文件
3. 运行与ISSM耦合的CUAS自旋初始化
4. 导出耦合所需的数据文件：ISSM与CUAS重启文件、季节强迫数据

## 后处理流程
### Greenland
本案例用于分析计算性能。实验目录命名遵循如下格式：work-<耦合方案>-<ISSM CPU核心数>-<CUAS CPU核心数>-<日期>-<时间>。对于性能分析运行，所使用的ISSM与CUAS-MPI构建版本未写入任何输出文件，这是因为集群的IO方差过大（如需生成诊断或其他用途的输出，可修改求解器/适配器配置）。其余步骤如前文所述使用Shell脚本执行。内置配置文件中已启用性能分析功能。

提供的脚本用于分析原始与聚合后的性能分析数据：
- analyze.sh：使用preCICE发行版自带的precice-profiling工具从原始数据中提取性能分析结果与跟踪数据。
- aggregate.py：加载单次或多次运行的跟踪数据并计算统计量（如多次运行、任务与耦合窗口的平均值）。
- plot_*.py：绘制性能结果的不同维度图表（如扩展性、映射对比）。
- archive.sh：将实验目录压缩为归档文件。

### Thule
本案例用于演示功能。后处理步骤如下：
- post-processing.sh：从单向耦合与双向耦合的模拟输出中生成衍生变量
- 单向耦合文件未包含正确的basal_velocity_ice场，因为未启用耦合
- 存在单位不一致问题（需在post-processing中修复）
- 空间平均计算
- （可选）使用CDO工具验证结果
- plot_*：绘制结果的地图与时间序列图表