Oceananigans.jl and ClimaOcean.jl

There is extensive documentation for the package Oceananigans with many links here.

Oceanigans Examples:

These examples are given to explore the way in which the Oceananigans package can be used to examine local properties of sea water. Below in the section "ClimaOcean Examples" more global examples will be provided once they have been verified.

These examples use the graphics package CairoMakie. To run them on a GPU some adjustments need to be made. For example the CUDA package must be used and instead of CairoMakie, the closely related GLMakie. The final example is for the reader to experiment interactively with a simple Julia function readme_example(arch, time, npts) to compare the performance of the CPU and GPU, if its available. It is taken from the Oceananigans.jl README.md documentation.

Hints for running the examples: We make no assumptions regarding special environments for running Julia. Our method of considering the examples is to first download the example code into a local directory or folder. Then run Julia in a command window with this local directory with whatever command line flags the user desires, including none. Open the example code in an editor, such as Notepad++, and then drag and drop into Julia blocks of code, such as those between begin and end in the "Adjusted version" of the example. Output will appear either on the screen such as plots or in the local directory.

Hints for obtaining help: Many Julia and Oceanigans methods (and their functions) amd structures appear in the examples. To get the extensive online help which is available, first ensure that "using Oceananigans, ClimaOcean" is invoked. In addition, if the GPU is being investigated then "using CUDA" should be invoked. Then Julia's normal help environment can be entered with a question mark on an othwise empty line. Then type the name of the symbol for which help is sought. A list of names is given on this page below. The descriptions and options are often many and might be bewildering at first. In the examples only a small number of options are explored.

These examples are taken from the Oceananigans.jl github file system.

  1. One Dimensional Diffusion:

    This simple example of one dimensional diffusion illustrates the way in which Oceanigans applications are normally structured. First the package environment, then the grid, model, initial condition, visualizing the model data with CairoMakie, running the simulation, and finally making a movie of the resulting flow. Roughly speaking, this progression is exhibited in each example.

    Code and documentation links:

  2. Two Dimensional Turbulence

    In this example, we initialize a random velocity field and observe its turbulent decay in a two-dimensional domain. This example demonstrates how to run a model with no tracers and no buoyancy model. and how to use computed `Field`s to generate output.

    Code and documentation links:

  3. Baroclinic Adjustment

    In this example, we simulate the evolution and the passage to equlibrium of a baroclinically unstable front.

    Code and documentation links:

  4. Internal Wave

    In this example, we initialize an internal wave packet in two-dimensions and watch it propagate. This example illustrates how to set up a two-dimensional model, set initial conditions, and how to use the structure BackgroundField.

    Code and documentation links:

  5. Tilted Bottom Boundary Layer

    This example simulates a two-dimensional oceanic bottom boundary layer in a domain that's tilted with respect to gravity. We simulate the perturbation away from a constant along-slope (y-direction) velocity constant density stratification. This perturbation develops into a turbulent bottom boundary layer due to momentum loss at the bottom boundary modeled with a quadratic drag law.

    The example illustrates the effects of changing the direction of gravitational acceleration in the buoyancy model and changing the axis of rotation for Coriolis forces.

    Code and documentation links:

  6. Shallow Water Bickley Jet

    This is an example of an unstable Bickley jet in a Shallow Water model.

    It uses Oceananigans.jl's ShallowWaterModel to simulate the evolution of an unstable, geostrophically balanced, Bickley jet The example is periodic in x with flat bathymetry and uses the conservative formulation of the shallow water equations. The initial conditions superpose the Bickley jet with small-amplitude perturbations. See ["The nonlinear evolution of barotropically unstable jets," J. Phys. Oceanogr. (2003)](https://doi.org/10.1175/1520-0485(2003)033<2173:TNEOBU>2.0.CO;2) for more details on this problem.

    The mass transport (uh, vh) is the prognostic momentum variable in the conservative formulation of the shallow water equations, where (u, v) are the horizontal velocity components and ``h`` is the layer height.

  7. Internal Tide

    In this example we show how an internal tide is generated from a barotropic tidal flow flowing back and forth over a sea bottom mount.

    Code and documentation links:

  8. Convecting Plankton

    This is an example modelling plankton mixing and blooming.

    We simulate the mixing of phytoplankton by convection that decreases in time and eventually shuts off, thereby precipitating a phytoplankton bloom. A similar scenario was simulated by [Taylor and Ferrari (2011)](https://aslopubs.onlinelibrary.wiley.com/doi/abs/10.4319/lo.2011.56.6.2293), providing evidence that the ["critical turbulence hypothesis"](https://en.wikipedia.org/wiki/Critical_depth#Critical_Turbulence_Hypothesis) explains the explosive bloom of oceanic phytoplankton observed in spring.

    The phytoplankton in our model are advected, diffuse, grow, and die according to

    ∂t P + (v · ∇) P - κ ∇²P = (μ₀ e(z / λ) - m) P
    where v is the turbulent velocity field, κ is an isotropic diffusivity, μ₀ is the phytoplankton growth rate at the surface, λ is the scale over which sunlight attenuates away from the surface, and m is the mortality rate of phytoplankton due to viruses and grazing by zooplankton. We use Oceananigans' Forcing abstraction to implement the phytoplankton dynamics described by the right side of the phytoplankton equation above.

    The example demonstrates how to:

    Code and documentation links:

  9. Ocean Wind Mixing And Convection

    This example simulates mixing by three-dimensional turbulence in an ocean surface boundary layer driven by atmospheric winds and convection. It demonstrates how to:

    Code and documentation links:

  10. Horizontal Convection

    In this example a non-uniform buoyancy is imposed on top of an initially resting fluid. It demonstrates how to:

    Code and documentation links:

  11. Langmuir Turbulence

    This example implements a Langmuir turbulence simulation reported in section 4 of [Wagner et al., "Near-inertial waves and turbulence driven by the growth of swell", Journal of Physical Oceanography (2021)](https://journals.ametsoc.org/view/journals/phoc/51/5/JPO-D-20-0178.1.xml)

    The example demonstrates how to:

    Code and documentation links:

  12. Kelvin Helmholtz Instability

    This example models the classical Kelvin-Helmholtz instability for two fluids, one on top of the other, moving in different directions in the (x,z) plane.

    Code and documentation links:

  13. Testing the GPU

    This simple example is of a Julia function readme_example(arch, time, npts) to compare the performance of the readers CPU and GPU. The first argument should be either CPU() or GPU(), the second the stop time, and the third the number of grid points in the x and y directions. Note that a comment has been made that for the GPU to perform better than the CPU there must be at least 10 million grid points, for example npts=104.

    Code link: An adjusted version of the original example Julia code is linked here.

A first example for ClimaOcean.jl

ClimaOcean is a package under development with a first example given here and more to come later. It supports the development of global climate models as well as local, based on bathymetry (heights and depths) from NASAs ECCO2 data set, the Japanese 55 year reanalysis JRA55-do data set, and the Julia packages Oceananigans.jl and CairoMakie.jl or GLMakie.jl. Most examples will be able to be adapted to run on GPUs with little change.

To see an explanation of the differences between Oceanigans and ClimaOcean, click here and scroll down below the Installation instructions.

Users need to be aware that this package, ClimaOcean, is in a state of evolution and the latest version ClimaOcean#main is more robust than earlier versions. Users also should be aware that, as of 15th October 2024, the bathymetry under Windows is not able to be loaded, thus excluding for the time being examples which use ECCO2.

The example given here is inspect_JRA55_any_two.jl, which is a modified form of the original inspect_JRA55_data.jl linked here. Note that instead of, currently, any two of the available data sets in JRA55 being available and covering a desirable set of variables, including for example sea level pressure and temperature, only downwelling short wave radiation and relative humidity gave expected results.

For more infomation regarding the JRA55 dataset, see the article by K. D. Stewart et al. entited "JRA55-do-based repeat year forcing datasets for driving ocean-sea-ice models" Ocean Modelling, 2020 accessible here.

The output with mouse control from the "display(fig)" statement is to the screen. A copy of the file output from the "save" statement is linked here. A version of the movie is here.

Some Oceanigans and ClimaOcean methods and structures

  1. Grids

  2. Models

  3. Simulations

  4. Numerical Solvers

  5. Turbulence Closures

  6. Boundary Conditions