ClimaCore.jl

The dynamical core (dycore) of the CliMA Earth System Model: composable, performance-portable tools for discretizing partial differential equations on the sphere and in Cartesian domains.

Documentation
Version
License
Tests
Code Coverage
Downloads
DOI

ClimaCore.jl is the spatial discretization layer of the Climate Modeling Alliance (CliMA) Earth System Model, written entirely in Julia. It supplies the grids, fields, and differential operators that ClimaAtmos.jl and ClimaLand.jl build their equations on, and time steps them with ClimaTimeSteppers.jl. Configurations range from a single column to large-eddy simulation on a box to a global cubed sphere, and it runs on a CPU, on many nodes through MPI, and on a GPU.

Features

• Horizontal spectral elements: continuous (CG) and discontinuous (DG) Galerkin discretizations on quadrilateral elements, selected by one keyword and completed across element boundaries by direct stiffness summation (CG) or numerical fluxes (DG).
• Staggered vertical finite differences: Lorenz staggering on cell centers and faces, with center-to-face and face-to-center operators and their boundary conditions.
• Upwinding and limiters: upwind-biased, FCT, and TVD reconstructions for advection, plus the quasi-monotone horizontal limiter and the vertical mass-borrowing limiter for positivity.
• Curvilinear geometry: covariant and contravariant bases, metric terms, and terrain-following coordinates, so operators apply to Cartesian and spherical domains alike.
• Matrix-free operators via broadcasting: differential operators act like functions when broadcast over a Field, fusing operators and function calls into a single pass and compiling to one CPU loop or one CUDA kernel.
• Performance portability and scaling: ClimaCore runs on CPUs and GPUs and distributes over MPI, with weak-scaling efficiency above 92% on GPUs and above 98% on CPUs, and 0.20 simulated years per day at 6 km resolution on 256 H100 GPUs (Yatunin et al. 2026).
• Differentiability: fields and operators carry ForwardDiff dual numbers, so a column tendency can be differentiated for Jacobians and calibration.
• Time-stepper compatible: Fields and FieldVectors are the state vector for ClimaTimeSteppers.jl.

Installation

ClimaCore.jl is a registered Julia package (Julia 1.10 or later):

using Pkg
Pkg.add("ClimaCore")

Quick Example

import ClimaComms
ClimaComms.@import_required_backends
import ClimaCore: Domains, Meshes, Spaces, Fields, Geometry, Operators

FT = Float64

# Build a 1D column: interval domain -> mesh -> finite-difference space
domain = Domains.IntervalDomain(
    Geometry.ZPoint{FT}(0),
    Geometry.ZPoint{FT}(2π),
    boundary_names = (:bottom, :top),
)
mesh = Meshes.IntervalMesh(domain; nelems = 128)
space = Spaces.CenterFiniteDifferenceSpace(ClimaComms.device(), mesh)

# Define a field over the space and differentiate it with a composed operator
z = Fields.coordinate_field(space).z
θ = sin.(z)
grad = Operators.GradientC2F(
    bottom = Operators.SetValue(FT(0)),
    top = Operators.SetValue(FT(0)),
)
∂θ = @. Geometry.WVector(grad(θ))   # face-valued vertical gradient (≈ cos(z))

This snippet is the Home page example, which the docs build runs on every commit. More runnable examples (column, plane, and sphere configurations) are in the examples/ directory.

Documentation

• Stable docs — tutorials, how-to guides, explanation of the numerics, and API reference
• Dev docs — latest development version
• examples/ — runnable examples across geometries

Integration with CliMA models

ClimaCore.jl is the dynamical core used throughout the CliMA ecosystem, including:

• ClimaAtmos.jl — atmosphere model
• ClimaLand.jl — land model

Device and communication backends come from ClimaComms.jl, and time integration from ClimaTimeSteppers.jl.

For developers

Downstream performance checks

A change that looks harmless in ClimaCore can cost a downstream model real time, so a separate Buildkite pipeline, .buildkite/perf/pipeline.yml, runs whole models against the development version of ClimaCore. It clones ClimaCoupler and ClimaLand at pinned commits, Pkg.develops ClimaCore into them, and benchmarks one AMIP configuration plus ClimaLand's global soil and snowy land models on a GPU. ClimaLand is the only model that runs with a land/sea mask, so those two steps are the only end-to-end coverage of the masked loop and column operator paths.

To trigger these tests, add [perf] to your commit message. The pipeline will show up as a GitHub status check on the pull request, separate from the main CI run. Each step attaches its timings, flame graphs and CUDA profiles as build artifacts.

Contributing

Contributors should follow the shared CliMA engineering standards in docs/dev-guides/, which cover architecture, performance, code quality, documentation, and workflows. These are vendored from CliMA/DeveloperGuides. The repo's AGENTS.md is a starting point for AI agents with repo-specific guidance.