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!](https://doi.org/10.1029/2024MS004465)), 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](https://github.com/CliMA/Oceananigans.jl/discussions/categories/jobs) for developer and user opportunities!
Testing infrastructure is provided by [atdepth](https://www.atdepth.org) and the [Climate Modeling Alliance](https://clima.caltech.edu).
## Contents
- [Contents](#contents)
- [Installation instructions](#installation-instructions)
- [Running your first model](#running-your-first-model)
- [The Oceananigans knowledge base](#the-oceananigans-knowledge-base)
- [Citing and otherwise spreading the word](#citing-and-otherwise-spreading-the-word)
- [Contributing](#contributing)
- [Movies](#movies)
- [Performance benchmarks](#performance-benchmarks)
## Installation instructions
Oceananigans is a [registered Julia package](https://julialang.org/packages/). So to install it,
1. [Download Julia](https://julialang.org/downloads/) (version 1.10 or later).
2. 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: 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](https://clima.github.io/OceananigansDocumentation/stable/) for more code examples and tutorials.
Below, you'll find [movies](#movies) from GPU simulations and a link to our [performance benchmarks](#performance-benchmarks).
## The Oceananigans knowledge base
It's _deep_ and includes:
* [Documentation](https://clima.github.io/OceananigansDocumentation/stable) 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](https://github.com/CliMA/Oceananigans.jl/discussions), covering topics like
* ["Computational science"](https://github.com/CliMA/Oceananigans.jl/discussions/categories/computational-science), or how to science and set up numerical simulations in Oceananigans, and
* ["Experimental features"](https://github.com/CliMA/Oceananigans.jl/discussions?discussions_q=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](https://github.com/CliMA/Oceananigans.jl/discussions/new?).
* The [Oceananigans wiki](https://github.com/CliMA/Oceananigans.jl/wiki) contains practical tips for [getting started with Julia](https://github.com/CliMA/Oceananigans.jl/wiki/Installation-and-getting-started-with-Oceananigans), [accessing and using GPUs](https://github.com/CliMA/Oceananigans.jl/wiki/Accessing-GPUs-and-using-Oceananigans-on-GPUs), and [productive workflows when using Oceananigans](https://github.com/CliMA/Oceananigans.jl/wiki/Productive-Oceananigans-workflows-and-Julia-environments).
* The [NumericalEarth slack](https://join.slack.com/t/numericalearth/shared_invite/zt-3pwpvky4k-XX7RkgQgHLIUt~wtwGXN~Q) where one may access institutional knowledge stored in the minds of the Oceananigans community!
* Consider also joining the [Julia Slack](https://julialang.org/slack/), yet another powerful community resource for the Julia package ecosystem, using GPUs, writing great Julia code, and hanging out.
* [Issues](https://github.com/CliMA/Oceananigans.jl/issues) and [pull requests](https://github.com/CliMA/Oceananigans.jl/pulls) 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](https://doi.org/10.48550/arXiv.2502.14148) 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](https://doi.org/10.48550/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 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},
}
