Productive Oceananigans workflows and Julia environments

This page describes some tips and practices that make Oceananigans-wielding computational scientists more productive.

Using environments

Julia environments specify a list of software packages --- and all of their dependencies! --- on which some piece of software or collection of scripts depends. Environments are the bedrock of shareable, reproducible --- sane! --- computational science projects that use the Julia programming language. What follows is the briefest of tutorials in Julia environments. Users who are new to Julia or don't know much about environments should also refer to the documentation.

For the Unix users out there, this code:

mkdir WowCoolSciences
cd WowCoolSciences
touch Project.toml
julia --project -e 'using Pkg; Pkg.add("Oceananigans")'

1. Makes a directory for the new Project
2. Makes a Project.toml file to describe the project's "environment"
3. Adds the latest tagged version of Oceananigans to the environment and installs every single package that you need to use Oceananigans.

When we type Pkg.add("Oceananigans") or alternatively pkg> add Oceananigans in the Julia REPL's "package manager mode", we install either the latest tagged version of Oceananigans, or the most recent version of Oceananigans that's compatible with other packages already added to the environment. For example, if your environment includes an ancient version of CUDA.jl that isn't supported by the latest Oceananigans, pkg> add Oceananigans will install an accordingly ancient version of Oceananigans. It's very much worth becoming proficient with Julia's package manager --- Pkg.add can install packages from any git tag or version, branch, unregistered repository, or local path.

Checking your Oceananigans version

Typing in a terminal

julia --project -e 'using Pkg; Pkg.status()'

or equivalently in Julia's package manager mode

pkg> st

lists all the packages and their versions in the current environment:

      Status `~/Desktop/WowCoolSciences/Project.toml`
  [9e8cae18] Oceananigans v0.75.1

This time, we installed Oceananigans version 0.75.1. But next time the version could be different! Automated dependency management and the installation of ancient Oceananigans versions is the source of many woes for unsuspecting users. Inexplicable syntax errors and ERROR: UndefVarError: XXXX not defined are symptomatic --- check your Oceananigans version!

Updating Oceananigans

In an existing environment, Oceananigans is updated by typing

julia --project -e 'using Pkg; Pkg.update("Oceananigans")

or, equivalently, by starting julia --project, pressing ] to enter package manager mode, and typing

(WowCoolSciences) pkg> up Oceananigans

But wait! Updating should be done with care, because Oceananigans syntax is always evolving and updating Oceananigans could break your scripts. If you're prepared to journey into the future then do not fear 🚀! Of course, if anything breaks and you don't know how to fix it, don't hesitate to get in touch.