Oceananigans.jl
🌊 Julia software for fast, friendly, flexible, ocean-flavored fluid dynamics on CPUs and GPUs
Install / Use
/learn @CliMA/Oceananigans.jlREADME
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
- 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:
<details><summary>bibtex</summary> <pre><code>@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 S. Bishnu 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}, }</code></pre> </details>"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
