Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

ClimaOcean.jl

A framework for realistic ocean-only and coupled ocean + sea-ice simulations driven by prescribed atmospheres and based on Oceananigans and ClimaSeaIce.
https://github.com/clima/climaocean.jl

Category: Cryosphere
Sub Category: Sea Ice

Keywords

climate-model fluid-dynamics fluid-dynamics-simulator machine-learning ocean-modelling

Keywords from Contributors

data-assimilation climate climate-change ocean climate-science land land-surface-model eddies oceanography partial-differential-equations

Last synced: about 10 hours ago
JSON representation

Repository metadata

🌎 Regional-to-global coupled ocean and sea ice simulations based on Oceananigans

README.md

[!IMPORTANT]
The generic coupling framework and data wrangling utilities originally developed in ClimaOcean are being moved to NumericalEarth.jl, a new package for building coupled Earth system models with interchangeable components.
ClimaOcean.jl will continue to exist as a focused package for realistic ocean and ocean + sea-ice simulations built on Oceananigans and ClimaSeaIce, depending on NumericalEarth for shared functionality.
See the discussion for more details.

DOI
Build status
Documentation
Documentation

Installation

ClimaOcean is a registered package. To install from a Julia REPL:

julia> using Pkg

julia> Pkg.add("ClimaOcean")

julia> Pkg.instantiate()

Use Pkg.add(url="https://github.com/CliMA/ClimaOcean.jl.git", rev="main") to install the latest version of ClimaOcean.
For more information, see the documentation for Pkg.jl.

Why? What's the difference between ClimaOcean and Oceananigans?

Oceananigans is a general-purpose library for ocean-flavored fluid dynamics.
ClimaOcean implements a framework for driving realistic Oceananigans simulations with prescribed atmospheres, and coupling them to prognostic sea ice simulations.

A core abstraction: ClimaOcean.OceanSeaIceModel

Our system for realistic modeling is anchored by ClimaOcean.OceanSeaIceModel, which encapsulates the ocean simulation, sea ice simulation, prescribed atmospheric state, and specifies how the three communicate.
To illustrate how OceanSeaIceModel works we set up a simulation on a grid with 10 vertical levels and 1/4-degree horizontal resolution:

using Oceananigans
using Oceananigans.Units
using Dates
using CUDA
import ClimaOcean

arch = GPU()
grid = LatitudeLongitudeGrid(arch,
                             size = (1440, 560, 10),
                             halo = (7, 7, 7),
                             longitude = (0, 360),
                             latitude = (-70, 70),
                             z = (-3000, 0))

bathymetry = ClimaOcean.regrid_bathymetry(grid) # builds gridded bathymetry based on ETOPO1
grid = ImmersedBoundaryGrid(grid, GridFittedBottom(bathymetry))

# Build an ocean simulation initialized to the ECCO state estimate version 2 on Jan 1, 1993
ocean = ClimaOcean.ocean_simulation(grid)
start_date = DateTime(1993, 1, 1)
set!(ocean.model,
     T=ClimaOcean.Metadatum(:temperature; date=start_date, dataset=ClimaOcean.ECCO2Daily()),
     S=ClimaOcean.Metadatum(:salinity;    date=start_date, dataset=ClimaOcean.ECCO2Daily()))

# Build and run an OceanSeaIceModel (with no sea ice component) forced by JRA55 reanalysis
atmosphere = ClimaOcean.JRA55PrescribedAtmosphere(arch)
coupled_model = ClimaOcean.OceanSeaIceModel(ocean; atmosphere)
simulation = Simulation(coupled_model, Δt=20minutes, stop_time=30days)
run!(simulation)

The simulation above achieves approximately 8 simulated years per day of wall time on an Nvidia H100 GPU.

Since ocean.model is an Oceananigans.HydrostaticFreeSurfaceModel, we can leverage Oceananigans features in our scripts.
For example, to plot the surface speed at the end of the simulation we write

u, v, w = ocean.model.velocities
speed = Field(sqrt(u^2 + v^2))
compute!(speed)

using GLMakie
heatmap(view(speed, :, :, ocean.model.grid.Nz), colorrange=(0, 0.5), colormap=:magma, nan_color=:lightgray)

which produces

image

Additional features: a utility for ocean_simulations and data wrangling

A second core abstraction in ClimaOcean is ocean_simulation. ocean_simulation configures an Oceananigans model for realistic simulations including temperature and salinity, the TEOS-10 equation of state, boundary conditions to store computed air-sea fluxes, the automatically-calibrated turbulence closure CATKEVerticalDiffusivity, and the WENOVectorInvariant advection scheme for mesoscale-turbulence-resolving simulations.

ClimaOcean also provides convenience features for wrangling datasets of bathymetry, ocean temperature, salinity, ocean velocity fields, and prescribed atmospheric states.

ClimaOcean is built on top of Oceananigans and ClimaSeaIce, so it's important that ClimaOcean users become proficient with Oceananigans.
Note that though ClimaOcean is currently focused on hydrostatic modeling with Oceananigans.HydrostaticFreeSurfaceModel, realistic nonhydrostatic modeling is also within the scope of this package.

Citing

If you use ClimaOcean for your research, teaching, or fun 🤩, everyone in our community will be grateful
if you give credit by citing the corresponding Zenodo record, e.g.,

Wagner, G. L. et al. (2025). CliMA/ClimaOcean.jl: v0.8.10 (v0.8.10). Zenodo. https://doi.org/10.5281/zenodo.7677442

and also the recent preprint submitted to the Journal of Advances in Modeling Earth Systems that presents an overview of all the things that make Oceananigans unique:

"High-level, high-resolution ocean modeling at all scales with Oceananigans"

by Gregory L. Wagner, Simone Silvestri, Navid C. Constantinou, Ali Ramadhan, Jean-Michel Campin,
Chris Hill, Tomas Chor, Jago Strong-Wright, Xin Kai Lee, Francis Poulin, Andre Souza, Keaton J. Burns,
Siddhartha Bishnu, John Marshall, and Raffaele Ferrari

submitted to the Journal of Advances in Modeling Earth Systems, arXiv:2502.14148

Citation (CITATION.cff)

# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!

cff-version: 1.2.0
title: ClimaOcean.jl
message: >
  If you use ClimaOcean.jl in your research, teaching, or
  for fun, please cite it using the metadata below.
type: software
authors:
  - family-names: Wagner
    given-names: Gregory L.
    orcid: 'https://orcid.org/0000-0001-5317-2445'
    affiliation: 'Aeolus Labs, Massachusetts Institute of Technology'
  - family-names: Constantinou
    given-names: Navid C.
    orcid: 'https://orcid.org/0000-0002-8149-4094'
    affiliation: University of Melbourne
  - family-names: Silvestri
    given-names: Simone
    orcid: 'https://orcid.org/0000-0002-7156-946X'
    affiliation: Politecnico di Torino
  - given-names: Jago
    family-names: Strong-Wright
    orcid: 'https://orcid.org/0000-0002-7174-5283'
    affiliation: University of Cambridge
  - given-names: Taimoor
    family-names: Sohail
    affiliation: University of Melbourne
    orcid: 'https://orcid.org/0000-0002-4162-3269'
  - given-names: Xin Kai
    family-names: Lee
    affiliation: Massachusetts Institute of Technology
    orcid: 'https://orcid.org/0000-0002-1411-9497'
identifiers:
  - type: doi
    value: 10.5281/zenodo.7677442
    description: The concept DOI of the work
repository-code: 'https://github.com/CliMA/ClimaOcean.jl'
url: 'https://github.com/CliMA/ClimaOcean.jl'
keywords:
  - ocean modelling
  - regional ocean modelling
  - GPU computing
  - Julia
  - global ocean modelling
  - climate modelling
license: MIT

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 2 days ago

Total Commits: 645
Total Committers: 26
Avg Commits per committer: 24.808
Development Distribution Score (DDS): 0.611

Commits in past year: 166
Committers in past year: 15
Avg Commits per committer in past year: 11.067
Development Distribution Score (DDS) in past year: 0.675

Name Email Commits
Gregory Wagner w****g@g****m 251
Simone Silvestri s****0@g****m 176
Navid C. Constantinou n****y 121
github-actions[bot] 4****] 20
Julia Sloan 5****5 16
Jago Strong-Wright j****w@p****m 9
CompatHelper Julia c****y@j****g 7
Taimoor Sohail t****l@g****m 7
Xin Kai Lee 5****i 7
Simon Byrne s****e@g****m 6
Gabriele Bozzola g****a@c****u 5
dependabot[bot] 4****] 3
Dave Rumph 6****h 2
Jonathan Lauderdale j****e@g****m 2
Nora Loose N****e 2
John Eismeier 4****i 1
Josué Martínez Moreno j****o@g****m 1
Kevin Broughan b****n@g****m 1
Michel Schanen m****n@g****m 1
Mosè Giordano 7****o 1
Nat Efrat-Henrici 6****i 1
Steve Penny S****y 1
Tapio Schneider t****o@c****u 1
Valentin Churavy v****y 1
William Moses gh@w****m 1
Zhaoyi Shen 1****1 1

Committer domains:

Issue and Pull Request metadata

Last synced: 4 days ago

Total issues: 182
Total pull requests: 670
Average time to close issues: about 1 month
Average time to close pull requests: 17 days
Total issue authors: 22
Total pull request authors: 26
Average comments per issue: 2.82
Average comments per pull request: 3.11
Merged pull request: 444
Bot issues: 1
Bot pull requests: 63

Past year issues: 37
Past year pull requests: 140
Past year average time to close issues: about 1 month
Past year average time to close pull requests: 5 days
Past year issue authors: 14
Past year pull request authors: 14
Past year average comments per issue: 2.68
Past year average comments per pull request: 2.76
Past year merged pull request: 88
Past year bot issues: 1
Past year bot pull requests: 20

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/clima/climaocean.jl

Top Issue Authors

  • glwagner (70)
  • navidcy (35)
  • simone-silvestri (24)
  • xkykai (9)
  • francispoulin (8)
  • taimoorsohail (8)
  • waywardpidgeon (7)
  • NoraLoose (3)
  • Sbozzolo (3)
  • sb4233 (2)
  • uganzedo1974 (2)
  • JuliaTagBot (1)
  • ffrancesco94 (1)
  • kevinbroughan (1)
  • thopri (1)

Top Pull Request Authors

  • simone-silvestri (218)
  • glwagner (201)
  • navidcy (108)
  • github-actions[bot] (60)
  • taimoorsohail (20)
  • Sbozzolo (8)
  • giordano (6)
  • xkykai (4)
  • seamanticscience (4)
  • michel2323 (4)
  • francispoulin (4)
  • juliasloan25 (4)
  • vtamsitt (4)
  • dependabot[bot] (3)
  • NoraLoose (3)

Top Issue Labels

  • data wrangling (15)
  • bug (13)
  • documentation (10)
  • bathymetry ⛰️ (8)
  • question (7)
  • user interface (6)
  • tests (5)
  • global simulations 🌎 (5)
  • enhancement (3)
  • help wanted (2)
  • performance (2)
  • SDI (1)
  • sea ice 🧊 (1)
  • extensions 🧬 (1)
  • tagbot-manual (1)
  • ice-ocean coupling🧊 🌊 (1)
  • output 💾 (1)
  • cleanup 🧹 (1)

Top Pull Request Labels

  • build docs (75)
  • documentation (40)
  • data wrangling (25)
  • bug (18)
  • cleanup 🧹 (10)
  • enhancement (9)
  • Run examples (8)
  • tests (8)
  • Built Docs (8)
  • atmosphere-ocean coupling ⛅️ 🌊 (8)
  • user interface (8)
  • bathymetry ⛰️ (8)
  • 🚨 DO NOT MERGE 🚨 (6)
  • dependencies (6)
  • extensions 🧬 (3)
  • github_actions (3)
  • output 💾 (3)
  • ice-ocean coupling🧊 🌊 (1)
  • global simulations 🌎 (1)

Package metadata

juliahub.com: ClimaOcean

🌎 Regional-to-global coupled ocean and sea ice simulations based on Oceananigans

  • Homepage: https://clima.github.io/ClimaOceanDocumentation/stable/
  • Documentation: https://docs.juliahub.com/General/ClimaOcean/stable/
  • Licenses: MIT
  • Latest release: 0.9.4 (published 2 months ago)
  • Last Synced: 2026-04-01T03:57:50.842Z (about 1 month ago)
  • Versions: 60
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 3,485 Last month
  • Rankings:
    • Dependent repos count: 9.576%
    • Average: 24.113%
    • Dependent packages count: 38.649%

Dependencies

.github/workflows/CompatHelper.yml actions
  • julia-actions/setup-julia v1 composite
.github/workflows/DocPreviewCleanup.yml actions
  • actions/checkout v3 composite
.github/workflows/Documenter.yml actions
  • actions/checkout v3 composite
  • julia-actions/setup-julia latest composite
  • styfle/cancel-workflow-action 0.8.0 composite
.github/workflows/TagBot.yml actions
  • JuliaRegistries/TagBot v1 composite
.github/workflows/ci.yml actions
  • actions/cache v3 composite
  • actions/checkout v3 composite
  • codecov/codecov-action v2 composite
  • julia-actions/julia-buildpkg v1 composite
  • julia-actions/julia-processcoverage v1 composite
  • julia-actions/julia-runtest v1 composite
  • julia-actions/setup-julia latest composite

Score: 16.697523589954095