ClimaCoupler.jl provides coupled system time stepping control and support for mapping import and export boundary information between components. It can handle atmosphere, ocean, land, and sea ice component models, and the source code is agnostic to the internals of these component models.
ClimaCoupler.jl targets global, long-term climate simulations, specifically for the Coupled Model Intercomparison Project (CMIP) and Atmospheric Model Intercomparison Project (AMIP). With these objectives in mind, this coupler is also designed to be flexible and modular, so it supports simpler slabplanet-type setups as well.
The experiments/ directory contains run scripts
for CMIP, AMIP, and slabplanet setups. A few simple component models are implemented
within src/, while more complex component models extend the ClimaCoupler interface
in ext/.
| Documentation |   |
| Unit Tests |   |
| Downloads |  |
Recommended Julia Version: Stable release v1.12.x, CI tests Julia v1.10 and 1.12.
Here we will focus on the AMIP experiment, which uses the environment in the experiments/AMIP/ subdirectory of ClimaCoupler.jl
The first step to do this is to install all required packages for the environment using the following Julia command:
julia --project=experiments/AMIP -E "using Pkg; Pkg.instantiate(); Pkg.build()"Now you're ready to run the experiment, which uses the run_simulation.jl driver. To run interactively:
julia --project=experiments/AMIP
julia> include("experiments/AMIP/run_simulation.jl")
Or to run from the terminal:
julia --project=experiments/AMIP experiments/AMIP/run_simulation.jlWhen running from the terminal, you can also specify a configuration file to use for the simulation setup, and a job ID to keep track of this run's output.
Existing configuration files are specified in the config/ directory within ClimaCoupler.jl.
For example, to run the default AMIP configuration, you could use the following command:
julia --project=experiments/AMIP experiments/AMIP/run_simulation.jl --config_file config/ci_configs/amip_default.yml --job_id amip_defaultOutput from your run will be saved in the folder output/<job_id>/.
If no configuration file is specified, the default
amip_default.yml will be used, and output will be saved in output/amip_default/.
The output will take up approximately 1GB of space, and the simulation will take around 10 minutes to run on a single CPU, or less time on multiple CPUs or GPU.
Note: If you want to set the configuration file to something other than the default
while running the driver interactively, you'll need to
manually set the value for config_file.
For example, to use the configuration file found at config/ci_configs/amip_default.yml, you would set config_file
as follows in the run_simulation.jl driver:
config_file = "config/ci_configs/amip_default.yml"
If you don't intend to run your simulation using MPI, but you see an error about MPI and your simulation crashes, ClimaComms may be incorrectly selecting the configuration for your run. In this case, you can force ClimaComms to ignore MPI with
export CLIMACOMMS_CONTEXT="SINGLETON"
from the terminal, or
ENV["CLIMACOMMS_CONTEXT"]="SINGLETON"
from within the Julia environment before running the experiment.
Sometimes this happens when you are running in an interactive SLURM session.
Additionally, there are some environment variables we must set in these cases.
To run on GPU, we need to run export CLIMACOMMS_DEVICE="CUDA" in the terminal, or
ENV["CLIMACOMMS_DEVICE"]="CUDA" within the Julia environment before running the experiment.
To run with MPI, we need to run export CLIMACOMMS_CONTEXT="MPI" in the terminal, or
ENV["CLIMACOMMS_CONTEXT"]="MPI" within the Julia environment before running the experiment.
The main difference between running code locally vs running remotely is the module loading step. CliMA uses ClimaModules to coordinate the modules needed to run CliMA code on Caltech's clusters.
On Central, you can load the appropriate module package by running the following in the terminal:
export MODULEPATH="/resnick/groups/esm/modules:$MODULEPATH"
module load climacommon
Remember: This should be done after requesting a compute node, using the command
srun --pty -t 01:00:00 -p expansion bashor similar
On clima, you can load the appropriate module package by running the following in the terminal:
module load common
For additional information about these clusters, including how to gain access for the first time, see our slurm-buildkite wiki pages for Central and clima.
The run_simulation.jl driver contains two modes: the full AMIP mode and a Slabplanet mode, where all surfaces are thermal slabs. Since AMIP is not a closed system, the Slabplanet mode is useful for checking conservation properties of the coupling.
Running a Slabplanet simulation is the same as running an AMIP simulation, except for the specifics of the configuration file provided, so all information from the Running AMIP section will apply here too. Note that the default configuration used by run_simulation.jl specifies an AMIP simulation, so a configuration file must be specified to run a Slabplanet simulation. This can be done as follows:
julia --project=experiments/AMIP experiments/AMIP/run_simulation.jl --config_file config/ci_configs/slabplanet_default.yml --job_id slabplanet_defaultTo ensure that conservation is tracked throughout the experiment, the energy_check field of the configuration file must be set to true.