ClimaComms

ClimaComms.jl is a small package that provides abstractions for different computing devices and environments. ClimaComms.jl is use extensively by CliMA packages to control where and how simulations are run (e.g., one on core, on multiple GPUs, et cetera).

This page highlights the most important user-facing ClimaComms concepts. If you are using ClimaComms as a developer, refer to the Developing with ClimaComms page. For a detailed list of all the functions and objects implemented, the APIs page collects all of them.

Devices and Contexts

The two most important objects in ClimaComms.jl are the Device and the Context.

A Device identifies a computing device, a piece of hardware that will be executing some code. The Devices currently implemented are

• CPUSingleThreaded, for a CPU core with a single thread;
• CUDADevice, for a single CUDA-enabled GPU.

Devices are part of Contexts, objects that contain information require for multiple Devices to communicate. Implemented Contexts are

• SingletonCommsContext, when there is no parallelism;
• MPICommsContext , for a MPI-parallelized runs.

To choose a device and a context, most CliMA packages use the device() and context() functions. These functions look at specific environment variables and set the device and context accordingly. By default, the CPUSingleThreaded device is chosen and the context is set to SingletonCommsContext unless ClimaComms detects being run in a standard MPI launcher (as srun or mpiexec).

For example, to run a simulation on a GPU, run julia as

export CLIMACOMMS_DEVICE="CUDA"
export CLIMACOMMS_CONTEXT="SINGLETON"
# call/open julia as usual

Running with MPI/CUDA

CliMA packages do not depend directly on MPI or CUDA, so, if you want to run your simulation in parallel mode and/or on GPUs, you will need to install some packages separately.

For parallel simulations, MPI.jl, and for GPU runs, CUDA.jl. You can install these packages in your base environment

julia -E "using Pkg; Pkg.add(\"CUDA\"); Pkg.add(\"MPI\")"

Some packages come with environments that includes all possible backends (typically .buildkite). You can also consider directly using those environments.