ClimaComms.jl

ClimaComms.jl provides the abstractions for computing devices and communication contexts on which the CliMA ecosystem is built. It lets the same simulation code run unchanged on a single CPU thread, on multiple CPU threads, on NVIDIA GPUs, and across many nodes with MPI: the device and the parallelism are selected at runtime, typically through environment variables.

The two central abstractions

A device (ClimaComms.AbstractDevice) identifies the hardware that executes code. The devices currently implemented are

CPUSingleThreaded: a CPU using a single thread,
CPUMultiThreaded: a CPU using multiple threads,
CUDADevice: a single CUDA-enabled GPU.

A context (ClimaComms.AbstractCommsContext) is the environment through which processes communicate. It wraps a device and, for distributed runs, the information needed to exchange data between processes. The contexts currently implemented are

SingletonCommsContext: a single process, no parallelism;
MPICommsContext: distributed runs via MPI.

Devices and contexts are selected at runtime with the ClimaComms.device and ClimaComms.context functions, which read the CLIMACOMMS_DEVICE and CLIMACOMMS_CONTEXT environment variables. For example, to run a script on a GPU with four MPI processes:

export CLIMACOMMS_DEVICE="CUDA"
export CLIMACOMMS_CONTEXT="MPI"
mpiexec -n 4 julia --project script.jl

Note

Some packages provide additional ways to control the device and context (e.g., configuration files). Refer to the documentation of the specific package to learn more.

Where to go next

Getting Started: install ClimaComms and write a first script that runs on any device and any number of processes.
How-to Guide: recipes for common tasks, such as running on GPUs, writing device-agnostic loops, and setting up logging for MPI runs.
Design Philosophy: why ClimaComms exists, how it is designed, and how the CliMA packages use it.
Logging: loggers for distributed runs.
Frequently Asked Questions: solutions to common problems.
APIs: the complete API reference.