Installation and getting started with Oceananigans

Oceananigans installation is "often" simple

Sure, Oceananigans is "easy to use", but is it "easy to install"? In the majority of cases, installing Oceananigans "just" requires installing Julia, starting Julia, and typing

julia> using Pkg

julia> Pkg.add("Oceananigans")

(For more information about installing packages in Julia, see the Pkg documentation.)

The rest of us --- users who are new to Julia, users with non-standard hardware, or users who are simply new to text editing Unicode characters --- have this wiki page to consult for more detailed information.

Installing Julia

Most users install Julia by downloading a pre-built binary.

If a pre-built binary is not available for your system (for example, if you're on a POWER9 system), you may need to build Julia from source. Don't worry: building from source requires only a few extra steps in most cases (cloning the repository, finding the git tag you'd like to build, and typing make). Julialang's github has the info you need.

Julia v1.7 + Apple M1 Chip

If you use Julia v1.7 on an Apple machine with the new M1 chips then you may run into trouble. To overcome this, pin MPICH_jll to version 4.0.1 before installing Oceananigans:

julia> using Pkg; Pkg.add(name="MPICH_jll", version="4.0.1"); Pkg.build()

julia> Pkg.add("Oceananigans")

Programming in Julia

Using Oceananigans means writing Julia scripts, so all users of Oceananigans benefit from basic Julia programming knowledge. If you're new to programming in Julia, we recommend starting here, and then checking out this list of tutorials.

Using Oceananigans

The Julia REPL is seaworthy for initial forays into Oceananigans code. The REPL provides an interactive prompt with searchable history, tab-completion, helpful keybindings, "shell mode" and "package manager mode", and more. Scripts --- which are text files with names that end in .jl by convention --- can be run from the REPL with

julia> include("awesome_oceananigans.jl")

or from a terminal by typing

julia --project awesome_oceananigans.jl

Editing and reading unicode text in .jl files

The Oceananigans API makes heavy use of Unicode. Obviously, it's wonderful that Julia supports Unicode input and recognizes that

julia> 🦦, 🐋, ❤️  = 1, 2, 3
(1, 2, 3)

julia> 🦦 + 🐋 == ❤️
true

But we have to admit there are some downsides to Unicode, such as figuring out how to type Unicode characters on keys that have letters, but not otters, or finding fonts that don't display ⍰ for half the characters in what might've been a beautifully-written script.

If you're totally new to programming, we recommend editing text and Unicode with VSCode and using the VSCode extension for Julia.

If you're an experienced programmer and want to use other, familiar text editing tools to write Julia and Oceananigans scripts, you may need to do some research to adapt to the demands of reading and editing Unicode. For example, there's Unicode and Julia syntax support for vim.