Skip to content

CliMA/Oceananigans.jl

This branch is 13 commits ahead of main.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

0e02a2b · Dec 15, 2024
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024
Dec 13, 2024
Nov 14, 2024
Jul 28, 2023
Dec 15, 2024
Dec 14, 2024
Dec 13, 2024
Sep 21, 2024
Sep 12, 2021
Aug 10, 2024
Nov 8, 2024
Apr 11, 2023
Dec 14, 2024
Sep 6, 2024
Aug 27, 2020

Repository files navigation

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

Repo status MIT license Ask us anything ColPrac: Contributor's Guide on Collaborative Practices for Community Packages JOSS

GitHub tag (latest SemVer pre-release) Stable documentation Development documentation

Downloads per month Downloads per month

Buildkite CPU+GPU build status Docker build status

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

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

  1. Download Julia (version 1.9 or later).

  2. 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: 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:

Citing

If you use Oceananigans.jl as part of your research, teaching, or other activities, we would be grateful if you could cite our work and mention Oceananigans.jl by name.

@article{OceananigansJOSS,
  doi = {10.21105/joss.02018},
  url = {https://doi.org/10.21105/joss.02018},
  year = {2020},
  publisher = {The Open Journal},
  volume = {5},
  number = {53},
  pages = {2018},
  author = {Ali Ramadhan and Gregory LeClaire Wagner and Chris Hill and Jean-Michel Campin and Valentin Churavy and Tim Besard and Andre Souza and Alan Edelman and Raffaele Ferrari and John Marshall},
  title = {{Oceananigans.jl: Fast and friendly geophysical fluid dynamics on GPUs}},
  journal = {Journal of Open Source Software}
}

We also maintain a list of publications using Oceananigans.jl. If you have work using Oceananigans.jl 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

Watch deep convection in action

Watch free convection in action

Watch winds blowing over the ocean

Watch free convection with wind stress in action

Performance benchmarks

We've performed some preliminary 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).

This is not really a fair comparison as we haven't parallelized across all the CPU's cores so we will revisit these benchmarks once Oceananigans.jl can run on multiple CPUs and GPUs.

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