Oceananigans.jl

Fast and friendly fluid dynamics on CPUs and GPUs.
https://github.com/clima/oceananigans.jl

Category: Hydrosphere
Sub Category: Ocean Models

Keywords

climate climate-change data-assimilation fluid-dynamics gpu julia machine-learning ocean

Keywords from Contributors

ocean-modelling climate-model oceanography climate-science sciml differential-equations pde fluid-dynamics-simulator dae differentialequations

Last synced: about 22 hours ago
JSON representation

Repository metadata

🌊 Julia software for fast, friendly, flexible, ocean-flavored fluid dynamics on CPUs and GPUs

Host: GitHub
URL: https://github.com/clima/oceananigans.jl
Owner: CliMA
License: mit
Created: 2018-10-13T14:15:44.000Z (almost 8 years ago)
Default Branch: main
Last Pushed: 2026-08-06T02:19:57.000Z (7 days ago)
Last Synced: 2026-08-06T21:20:43.092Z (7 days ago)
Topics: climate, climate-change, data-assimilation, fluid-dynamics, gpu, julia, machine-learning, ocean
Language: Julia
Homepage: https://clima.github.io/OceananigansDocumentation/stable
Size: 56.7 MB
Stars: 1,392
Watchers: 33
Forks: 288
Open Issues: 344
Releases: 413
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
- Agents: AGENTS.md

Oceananigans is a fast, friendly, flexible software package for finite volume simulations of the nonhydrostatic
and hydrostatic Boussinesq equations on CPUs and GPUs.
It runs on GPUs (wow, fast!), though we believe Oceananigans makes the biggest waves
with its ultra-flexible user interface that makes simple simulations easy, and complex, creative simulations possible.
Oceananigans development is community-driven with contributors from academia and industry -
see jobs discussions for developer and user opportunities!
Testing infrastructure is provided by atdepth and the Climate Modeling Alliance.

Contents
Installation instructions
Running your first model
The Oceananigans knowledge base
Citing and otherwise spreading the word
Contributing
Movies
Performance benchmarks

Installation instructions

Oceananigans is a registered Julia package. So to install it,

Download Julia (version 1.10 or later).
Launch Julia and type

julia> using Pkg

julia> Pkg.add("Oceananigans")

This installs the latest version that's compatible with your current environment.
Don't forget to be careful 🏄 and check which Oceananigans you installed:

julia> Pkg.status("Oceananigans")

Running your first model

Let's run a two-dimensional, horizontally-periodic simulation of turbulence using 128² finite volume cells for 4 non-dimensional time units:

using Oceananigans
grid = RectilinearGrid(CPU(), size=(128, 128), x=(0, 2π), y=(0, 2π), topology=(Periodic, Periodic, Flat))
model = NonhydrostaticModel(grid; advection=WENO())
ϵ(x, y) = 2rand() - 1
set!(model, u=ϵ, v=ϵ)
simulation = Simulation(model; Δt=0.01, stop_time=4)
run!(simulation)

But there's more: loading CUDA.jl (via using CUDA) and changing CPU() to GPU() makes this code run on a CUDA-enabled Nvidia GPU.

Dive into the documentation for more code examples and tutorials.
Below, you'll find movies from GPU simulations along with CPU and GPU performance benchmarks.

The Oceananigans knowledge base

It's deep and includes:

Documentation that provides
- example Oceananigans scripts,
- tutorials that describe key Oceananigans objects and functions,
- explanations of Oceananigans finite-volume-based numerical methods,
- details of the dynamical equations solved by Oceananigans models, and
- a library documenting all user-facing Oceananigans objects and functions.
Discussions on the Oceananigans github, covering topics like
- "Computational science", or how to science and set up numerical simulations in Oceananigans, and
- "Experimental features", which covers new and sparsely-documented features for those who like to live dangerously.
If you've got a question or something, anything! to talk about, don't hesitate to start a new discussion.
The Oceananigans wiki contains practical tips for getting started with Julia, accessing and using GPUs, and productive workflows when using Oceananigans.
The NumericalEarth slack where one may access institutional knowledge stored in the minds of the Oceananigans community!
Consider also joining the Julia Slack, yet another powerful community resource for the Julia package ecosystem, using GPUs, writing great Julia code, and hanging out.
Issues and pull requests also contain lots of information about problems we've found, solutions we're trying to implement, and dreams we're dreaming to make tomorrow better 🌈.

Citing and otherwise spreading the word

If you use Oceananigans for your research, teaching, or fun 🤩, everyone in our community will be grateful
if you credit Oceananigans by name.

The community has published a number of articles describing the development of Oceananigans,
including a 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

Please cite this 👆 overview paper if you use Oceananigans in published work.

We've also published/submitted several model development papers. Please cite these below 👇 if you use
the features they describe! Also, if you have developed a new feature in Oceananigans and describe it in a paper, make sure to open a pull request to add it to this list:

Silvestri et al. (2026), "A low-storage Runge-Kutta framework for nonlinear free-surface ocean models".

This paper describes the development of a Runge-Kutta timestepping scheme for the HydrostaticFreeSurfaceModel.
Moses et al. (2026), "DJ4Earth: Differentiable, and performance-portable Earth system modeling via program transformations".

This paper describes the development and advantages of a strategy that leverages Enzyme.jl and Reactant.jl for building differentiable Oceananigans workflows.
Silvestri et al. (2025), "A new WENO-Based momentum advection scheme for simulations of ocean mesoscale turbulence".

This paper describes the development of WENOVectorInvariant() advection scheme, which can be used as the
momentum_advection scheme for HydrostaticFreeSurfaceModel.
Silvestri et al. (2025), "A GPU-based ocean dynamic core for routine mesoscale-resolving climate simulations".

This paper describes the optimization of the HydrostaticFreeSurfaceModel algorithm, including the implementation
of a new SplitExplicitFreeSurface algorithm for Distributed architectures for multiple GPUs. As a result of this work,
global simulations with O(10 km) grid spacing can be run on 16-20 nodes, achieving 10 simulated years per day (SYPD).
Wagner et al. (2025), "Formulation and calibration of CATKE, a one-equation parameterization for microscale ocean mixing".

This paper describes the development of CATKEVerticalDiffusivity(), including how it was automatically calibrated to
a suite of 35 large eddy simulations (also run with Oceananigans). It additionally features solutions from TKEDissipationVerticalDiffusivity (also known as "k-epsilon").
Ramadhan et al. (2020), "Oceananigans.jl: Fast and friendly geophysical fluid dynamics on GPUs".

This article in the Journal of Open Source Software describes an early version of Oceananigans' NonhydrostaticModel.

We also maintain a list of publications using Oceananigans.jl.
If you have work using Oceananigans that you would like to have listed there, please open a pull request to add it or let us know!

Contributing

If you're interested in contributing to the development of Oceananigans we want your help no matter how big or small a contribution you make!
Cause we're all in this together.

If you'd like to work on a new feature, or if you're new to open source and want to crowd-source neat projects that fit your interests, you should start a discussion right away.

For more information check out our contributor's guide.

Movies

Deep convection

Free convection

Winds blowing over the ocean

Free convection with wind stress

Performance benchmarks

We continuously measure the performance of Oceananigans by initializing models of various sizes with different schemes and closures and measuring the wall clock time taken per model iteration (or time step). These benchmarks are run on every commit in main and tracked on our performance dashboard.

To make full use of or fully saturate the computing power of a GPU such as an Nvidia Tesla V100 or
a Titan V, the model should have around ~10 million grid points or more.

Sometimes counter-intuitively running with Float32 is slower than Float64. This is likely due
to type mismatches causing slowdowns as floats have to be converted between 32-bit and 64-bit, an
issue that needs to be addressed meticulously. Due to other bottlenecks such as memory accesses and
GPU register pressure, Float32 models may not provide much of a speedup so the main benefit becomes
lower memory costs (by around a factor of 2).

Performance benchmark plots

Citation (CITATION.cff)

cff-version: 1.2.0
title: Oceananigans.jl
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - family-names: Oceananigans contributors
identifiers:
  - type: doi
    value: 10.5281/zenodo.4019271
repository-code: 'https://github.com/CliMA/Oceananigans.jl'
url: 'https://clima.github.io/OceananigansDocumentation/stable/'
abstract: Julia software for fast, friendly, flexible, ocean-flavored fluid dynamics on CPUs and GPUs.
license: MIT
preferred-citation:
  type: article
  authors:
  - family-names: "Ramadhan"
    given-names: "Ali"
    orcid: "https://orcid.org/0000-0003-1102-1520"
  - family-names: "Wagner"
    given-names: "Gregory LeClaire"
    orcid: "https://orcid.org/0000-0001-5317-2445"
  - family-names: "Hill"
    given-names: "Chris"
  - family-names: "Jean-Michel"
    given-names: "Campin"
  - family-names: "Churavy"
    given-names: "Valentin"
    orcid: "https://orcid.org/0000-0002-9033-165X"
  - family-names: "Souza"
    given-names: "Andre"
    orcid: "https://orcid.org/0000-0001-8025-3558"
  - family-names: "Edelman"
    given-names: "Alan"
    orcid: "https://orcid.org/0000-0001-7676-3133"
  - family-names: "Ferrari"
    given-names: "Raffaele"
    orcid: "https://orcid.org/0000-0003-1895-4294"
  - family-names: "Marshall"
    given-names: "John"
    orcid: "https://orcid.org/0000-0001-9230-3591"
  title: "Oceananigans.jl: Fast and friendly geophysical fluid dynamics on GPUs"
  journal: "Journal of Open Source Software"
  doi: "10.21105/joss.02018"
  volume: 5
  issue: 53
  start: 2018
  year: 2020

Owner metadata

Name: Climate Modeling Alliance
Login: CliMA
Email: clima@caltech.edu
Kind: organization
Description: An alliance of scientists, engineers and applied mathematicians, dedicated to pioneering a new, data-informed approach to climate modeling
Website: https://clima.caltech.edu
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/43161188?v=4
Repositories: 67
Last ynced at: 2023-03-03T21:04:27.588Z
Profile URL: https://github.com/CliMA

GitHub Events

Total

Create event: 965
Commit comment event: 247
Release event: 87
Delete event: 1005
Member event: 11
Pull request event: 1417
Fork event: 65
Discussion event: 11
Issues event: 467
Watch event: 258
Issue comment event: 4039
Push event: 7881
Pull request review event: 2624
Pull request review comment event: 2142

Last Year

Create event: 343
Commit comment event: 65
Release event: 16
Delete event: 292
Member event: 4
Pull request event: 414
Fork event: 11
Discussion event: 11
Issues event: 154
Watch event: 56
Issue comment event: 980
Push event: 2926
Pull request review comment event: 658
Pull request review event: 752

Committers metadata

Last synced: 1 day ago

Total Commits: 11,821
Total Committers: 98
Avg Commits per committer: 120.622
Development Distribution Score (DDS): 0.704

Commits in past year: 691
Committers in past year: 43
Avg Commits per committer in past year: 16.07
Development Distribution Score (DDS) in past year: 0.793

Name	Email	Commits
Ali Ramadhan	a**n@g**m	3500
Gregory Wagner	w**g@g**m	2687
Simone Silvestri	s**0@g**m	2019
Navid Constantinou	n**y@g**m	1873
Tomas Chor	t**r@g**m	674
Francis J. Poulin	f**n@u**a	270
Elise Palethorpe	e**y@g**m	78
Andre Souza	a**a@g**m	73
Mosè Giordano	7****o	72
suyashbire1	s**9@g**m	45
Jago Strong-Wright	j**t@g**m	38
hennyg888	h**2@h**m	38
Victoria Whitley	w**v@a**t	37
Xin Kai Lee	x**i@m**u	34
github-actions[bot]	4****]	34
Chris Hill	c**h@m**u	29
William Moses	gh@w****m	26
Benoît Pasquier	4****c	22
Sid	s**u@g**m	20
Joseph Kump	j**7@u**u	14
Valentin Churavy	v**y@g**m	14
dependabot[bot]	4****]	14
dkytezab	d**e@g**m	14
Jean-Michel Campin	j**c@m**u	13
Taimoor Sohail	t**l@u**u	11
Josef Bisits	j**s@g**m	10
CompatHelper Julia	c**y@j**g	10
Eliot Quon	e**t@a**h	6
Gabriele Bozzola	g**a@c**u	6
Alex Cavaliere	a**e@s**m	5
and 68 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 2 days ago

Total issues: 1,731
Total pull requests: 3,759
Average time to close issues: 7 months
Average time to close pull requests: 30 days
Total issue authors: 136
Total pull request authors: 97
Average comments per issue: 4.74
Average comments per pull request: 4.03
Merged pull request: 2,764
Bot issues: 0
Bot pull requests: 136

Past year issues: 75
Past year pull requests: 358
Past year average time to close issues: 15 days
Past year average time to close pull requests: 9 days
Past year issue authors: 26
Past year pull request authors: 33
Past year average comments per issue: 2.61
Past year average comments per pull request: 3.49
Past year merged pull request: 159
Past year bot issues: 0
Past year bot pull requests: 11

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

Top Issue Authors

glwagner (450)
ali-ramadhan (441)
navidcy (223)
tomchor (160)
francispoulin (73)
simone-silvestri (62)
xkykai (30)
jagoosw (19)
iuryt (14)
liuchihl (10)
mukund-gupta (8)
suyashbire1 (8)
Sumanshekhar17 (8)
sandreza (7)
taimoorsohail (7)

Top Pull Request Authors

glwagner (1,126)
navidcy (604)
simone-silvestri (568)
ali-ramadhan (449)
tomchor (235)
github-actions[bot] (120)
jagoosw (64)
francispoulin (54)
xkykai (50)
siddharthabishnu (45)
wsmoses (45)
giordano (34)
jlk9 (25)
christophernhill (16)
dependabot[bot] (16)

Top Issue Labels

bug 🐞 (237)
documentation 📜 (182)
cleanup 🧹 (154)
user interface/experience 💻 (149)
feature 🌟 (136)
question 💭 (135)
abstractions 🎨 (117)
testing 🧪 (110)
numerics 🧮 (99)
GPU 👾 (96)
performance 🏍️ (91)
output 💾 (59)
science 🌊 (57)
package 📦 (49)
grids 🗺️ (39)
help wanted 🦮 (39)
good first issue 🐤 (38)
distributed 🕸️ (31)
immersed boundaries ⛰️ (27)
🚨 high priority 🚨 (18)
turbulence closures 🎐 (17)
boundary conditions 🏓 (16)
cubed sphere 🧊🌎 (13)
extensions 🧬 (10)
models 🧫 (10)
duplicate 🧬 (9)
simulation 🎮 (7)
reactant ∇ (5)
🚲 bikeshedding (3)
benchmark performance (2)

Top Pull Request Labels

documentation 📜 (350)
bug 🐞 (183)
testing 🧪 (153)
cleanup 🧹 (133)
package 📦 (131)
user interface/experience 💻 (119)
numerics 🧮 (116)
GPU 👾 (107)
feature 🌟 (101)
output 💾 (85)
extensions 🧬 (82)
performance 🏍️ (72)
grids 🗺️ (69)
turbulence closures 🎐 (61)
distributed 🕸️ (60)
science 🌊 (54)
🚨 DO NOT MERGE 🚨 (51)
cubed sphere 🧊🌎 (44)
benchmark performance (40)
immersed boundaries ⛰️ (35)
abstractions 🎨 (32)
boundary conditions 🏓 (24)
dependencies (17)
models 🧫 (8)
validation scripts 💅🏼 (8)
simulation 🎮 (7)
julia (6)
reactant ∇ (6)
experimental feature 🧪 (5)
help wanted 🦮 (5)

Package metadata

Total packages: 3
Total downloads:
- julia: 13,317 last-month
Total dependent packages: 9 (may contain duplicates)
Total dependent repositories: 0 (may contain duplicates)
Total versions: 1,199

proxy.golang.org: github.com/CliMA/Oceananigans.jl

Homepage:
Documentation: https://pkg.go.dev/github.com/CliMA/Oceananigans.jl#section-documentation
Licenses: mit
Latest release: v0.110.14 (published 10 days ago)
Last Synced: 2026-08-12T02:01:44.165Z (1 day ago)
Versions: 413
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 5.401%
- Average: 5.583%
- Dependent repos count: 5.764%

proxy.golang.org: github.com/clima/oceananigans.jl

Homepage:
Documentation: https://pkg.go.dev/github.com/clima/oceananigans.jl#section-documentation
Licenses: mit
Latest release: v0.110.14 (published 10 days ago)
Last Synced: 2026-08-12T02:01:44.239Z (1 day ago)
Versions: 413
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 5.401%
- Average: 5.583%
- Dependent repos count: 5.764%

juliahub.com: Oceananigans