Oceananigans.jl

Oceananigans.jl: Fast and friendly geophysical fluid dynamics on GPUs - Published in JOSS (2020)

https://github.com/CliMA/Oceananigans.jl

Science Score: 85.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 12 DOI reference(s) in README
✓
Academic publication links
Links to: arxiv.org, joss.theoj.org
✓
Committers with academic emails
13 of 76 committers (17.1%) from academic institutions
✓
Institutional organization owner
Organization clima has institutional domain (clima.caltech.edu)
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (11.2%) to scientific vocabulary

Keywords

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

Keywords from Contributors

oceanography ocean-modelling graphics pdes ocean-sciences biogeochemistry simulations earth-observation meteorology ecology

Last synced: 6 months ago · JSON representation ·

Repository

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

Basic Info

Host: GitHub
Owner: CliMA
License: mit
Language: Julia
Default Branch: main
Homepage: https://clima.github.io/OceananigansDocumentation/stable
Size: 48.5 MB

Statistics

Stars: 1,163
Watchers: 33
Forks: 242
Open Issues: 247
Releases: 342

Topics

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

Created over 7 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Citation

Oceananigans.jl

🌊 Fast and friendly ocean-flavored Julia software for simulating incompressible fluid dynamics in Cartesian and spherical shell domains on CPUs and GPUs. https://clima.github.io/OceananigansDocumentation/stable

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.jl is developed by the Climate Modeling Alliance and heroic external collaborators.

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.9 or later).
Launch Julia and type

```julia 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 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:

julia 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: 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 #oceananigans channel on the Julia Slack, which accesses "institutional knowledge" stored in the minds of the amazing Oceananigans community.
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, John Marshall, Raffaele Ferrari

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

bibtex

@article{Oceananigans-overview-paper-2025,
  title = {{High-level, high-resolution ocean modeling at all scales with Oceananigans}},
  author = {G. L. Wagner and S. Silvestri and N. C. Constantinou and A. Ramadhan and J.-M. Campin and C. Hill and T. Chor and J. Strong-Wright and X. K. Lee and F. Poulin and A. Souza and K. J. Burns and J. Marshall and R. Ferrari},
  journal = {arXiv preprint},
  year = {2025},
  archivePrefix = {arXiv},
  eprint = {2502.14148},
  doi = {10.48550/arXiv.2502.14148},
  notes = {submitted to the Journal of Advances in Modeling Earth Systems},
}

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., "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., "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., "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., "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 perform some performance benchmarks (see the performance benchmarks section of the documentation) by initializing models of various sizes and measuring the wall clock time taken per model iteration (or time step).

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

Owner

Name: Climate Modeling Alliance
Login: CliMA
Kind: organization
Email: clima@caltech.edu

Website: https://clima.caltech.edu
Repositories: 67
Profile: https://github.com/CliMA

An alliance of scientists, engineers and applied mathematicians, dedicated to pioneering a new, data-informed approach to climate modeling

Citation (CITATION.cff)

cff-version: 1.2.0
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"
  - family-names: "Edelman"
    given-names: "Adam"
    orcid: "https://orcid.org/0000-0002-9033-165X"
  - family-names: "Ferrari"
    given-names: "Raffaele"
    orcid: "https://orcid.org/0000-0003-1895-4294"
  - family-names: "Marshall"
    given-names: "John"
  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

GitHub Events

Total

Fork event: 59
Create event: 646
Commit comment event: 188
Release event: 71
Issues event: 323
Watch event: 213
Delete event: 729
Member event: 8
Issue comment event: 3,174
Push event: 5,220
Pull request review event: 1,927
Pull request review comment event: 1,528
Pull request event: 1,043

Last Year

Fork event: 59
Create event: 646
Commit comment event: 188
Release event: 71
Issues event: 323
Watch event: 213
Delete event: 729
Member event: 8
Issue comment event: 3,174
Push event: 5,220
Pull request review event: 1,927
Pull request review comment event: 1,528
Pull request event: 1,043

Committers

Last synced: 7 months ago

All Time

Total Commits: 11,126
Total Committers: 76
Avg Commits per committer: 146.395
Development Distribution Score (DDS): 0.687

Past Year

Commits: 577
Committers: 29
Avg Commits per committer: 19.897
Development Distribution Score (DDS): 0.607

Top Committers

Name	Email	Commits
Ali Ramadhan	a**n@g**m	3,487
Gregory Wagner	w**g@g**m	2,544
Simone Silvestri	s**0@g**m	1,887
Navid Constantinou	n**y@g**m	1,749
Tomas Chor	t**r@g**m	623
Francis J. Poulin	f**n@u**a	269
Elise Palethorpe	e**y@g**m	78
Andre Souza	a**a@g**m	73
suyashbire1	s**9@g**m	45
hennyg888	h**2@h**m	38
Victoria Whitley	w**v@a**t	37
Jago Strong-Wright	j**t@g**m	35
github-actions[bot]	4****]	33
Chris Hill	c**h@m**u	29
William Moses	gh@w****m	23
Valentin Churavy	v**y@g**m	14
Jean-Michel Campin	j**c@m**u	13
Sid	s**u@g**m	12
Josef Bisits	j**s@g**m	10
CompatHelper Julia	c**y@j**g	10
Xin Kai Lee	5****i	8
Gabriele Bozzola	g**a@c**u	6
Alex Cavaliere	a**e@s**m	5
Avik Pal	a**l@m**u	5
iury simoes-sousa	i**t@p**e	5
Alexis Montoison	3****n	5
Kamontat Chantrachirathumrong	g**b@k**t	4
dependabot[bot]	4****]	4
Tim Besard	t**d@g**m	4
Keaton J. Burns	k**s@g**m	4
and 46 more...

Committer Domains (Top 20 + Academic)

mit.edu: 4 uwaterloo.ca: 1 att.net: 1 wsmoses.com: 1 julialang.org: 1 caltech.edu: 1 sharpnotions.com: 1 pm.me: 1 kamontat.net: 1 utexas.edu: 1 mail.de: 1 gmx.de: 1 jling.dev: 1 unimelb.edu.au: 1 cedar5.cedar.computecanada.ca: 1 protonmail.ch: 1 mac-barker-5-2.mit.edu: 1 ulg.ac.be: 1 ed.ac.uk: 1 anu.edu.au: 1 uci.edu: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 1,663
Total pull requests: 3,423
Average time to close issues: 7 months
Average time to close pull requests: about 1 month
Total issue authors: 123
Total pull request authors: 79
Average comments per issue: 4.75
Average comments per pull request: 4.05
Merged pull requests: 2,615
Bot issues: 0
Bot pull requests: 127

Past Year

Issues: 222
Pull requests: 1,160
Average time to close issues: 14 days
Average time to close pull requests: 9 days
Issue authors: 47
Pull request authors: 33
Average comments per issue: 3.02
Average comments per pull request: 2.57
Merged pull requests: 793
Bot issues: 0
Bot pull requests: 46

View more stats

Top Authors

Issue Authors

glwagner (445)
ali-ramadhan (439)
navidcy (219)
tomchor (149)
francispoulin (73)
simone-silvestri (58)
jagoosw (19)
xkykai (17)
iuryt (14)
liuchihl (10)
Sumanshekhar17 (8)
mukund-gupta (8)
suyashbire1 (8)
sandreza (7)
NoraLoose (7)

Pull Request Authors

glwagner (1,067)
navidcy (574)
simone-silvestri (499)
ali-ramadhan (442)
tomchor (212)
github-actions[bot] (118)
jagoosw (63)
francispoulin (54)
wsmoses (45)
siddharthabishnu (39)
xkykai (23)
jlk9 (20)
christophernhill (16)
avik-pal (15)
amontoison (15)

Top Labels

Issue Labels

bug 🐞 (229) documentation 📜 (177) cleanup 🧹 (154) user interface/experience 💻 (148) feature 🌟 (134) question 💭 (133) abstractions 🎨 (117) testing 🧪 (109) numerics 🧮 (98) GPU 👾 (90) performance 🏍️ (89) science 🌊 (57) output 💾 (56) package 📦 (47) good first issue 🐤 (38) help wanted 🦮 (38) grids 🗺️ (37) distributed 🕸️ (27) immersed boundaries ⛰️ (24) 🚨 high priority 🚨 (18) turbulence closures 🎐 (16) boundary conditions 🏓 (14) cubed sphere 🧊🌎 (13) models 🧫 (10) duplicate 🧬 (9) extensions 🧬 (8) simulation 🎮 (7) 🚲 bikeshedding (3) multithreading 🧵 (2) parameterizations (1)

Pull Request Labels

documentation 📜 (327) bug 🐞 (177) testing 🧪 (129) package 📦 (128) cleanup 🧹 (122) user interface/experience 💻 (115) numerics 🧮 (107) GPU 👾 (97) feature 🌟 (92) output 💾 (71) performance 🏍️ (67) extensions 🧬 (63) grids 🗺️ (61) turbulence closures 🎐 (56) science 🌊 (54) distributed 🕸️ (46) 🚨 DO NOT MERGE 🚨 (45) cubed sphere 🧊🌎 (40) immersed boundaries ⛰️ (33) abstractions 🎨 (30) boundary conditions 🏓 (20) benchmark performance (18) dependencies (9) models 🧫 (8) validation scripts 💅🏼 (8) simulation 🎮 (6) parameterizations (5) help wanted 🦮 (5) 🚲 bikeshedding (4) experimental feature 🧪 (4)

Packages

Total packages: 3
Total downloads:
- julia 315 total

Total dependent packages: 9
(may contain duplicates)
Total dependent repositories: 0
(may contain duplicates)
Total versions: 1,018

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

Documentation: https://pkg.go.dev/github.com/CliMA/Oceananigans.jl#section-documentation
License: mit
Latest release: v0.98.0
published 6 months ago

Versions: 341
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 5.4%

Average: 5.6%

Dependent repos count: 5.8%

Last synced: 6 months ago

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

Documentation: https://pkg.go.dev/github.com/clima/oceananigans.jl#section-documentation
License: mit
Latest release: v0.98.0
published 6 months ago

Versions: 341
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 5.4%

Average: 5.6%

Dependent repos count: 5.8%

Last synced: 6 months ago

juliahub.com: Oceananigans

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

Homepage: https://clima.github.io/OceananigansDocumentation/stable
Documentation: https://docs.juliahub.com/General/Oceananigans/stable/
License: MIT
Latest release: 0.97.8
published 7 months ago

Versions: 336
Dependent Packages: 9
Dependent Repositories: 0
Downloads: 315 Total

Rankings

Stargazers count: 0.4%

Forks count: 0.4%

Average: 6.0%

Dependent repos count: 6.1%

Dependent packages count: 17.0%

Last synced: 6 months ago

Dependencies

.github/workflows/CompatHelper.yml actions

julia-actions/setup-julia v1 composite

.github/workflows/TagBot.yml actions

JuliaRegistries/TagBot v1 composite

Dockerfile docker

julia 1.9.3 build

Oceananigans.jl

Science Score: 85.0%

Keywords

Keywords from Contributors

Basic Info

Statistics

Topics

Metadata Files

Oceananigans.jl

Contents

Installation instructions

Running your first model

The Oceananigans knowledge base

Citing and otherwise spreading the word

Contributing

Movies

Performance benchmarks

Citation (CITATION.cff)

GitHub Events

Total

Last Year

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

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

Rankings

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

Rankings

juliahub.com: Oceananigans

Rankings

Dependencies