Examples

There are several ways to use MITgcm.jl to e.g. analyze model results or run a new model simulation.

Note

Compiling MITgcm requires a fortran compiler. This is a requirement for all notebooks except MITgcm_configurations.jl.

Tip

The ECCO-Docker image has MITgcm.jl pre-installed, as well as gfortran, MPI, and NetCDF allowing to run any MITgcm configuration. The ECCO-Binder instance (free, but small) is available to try functionalities in the cloud.

Standard Modeling Workflow

Here is the standard way to run a model configuration using MITgcm.jl.

using MITgcm
MITgcm_download()
MC=MITgcm_config(configuration="advect_xy")

  ID            = 37ccfc0c-90c5-4bd7-9842-99b45ba28fa9
  model         = MITgcm
  configuration = advect_xy
  run folder    = /tmp/37ccfc0c-90c5-4bd7-9842-99b45ba28fa9
  log subfolder = /tmp/37ccfc0c-90c5-4bd7-9842-99b45ba28fa9/log

setup(MC)
build(MC,"--allow-skip")
log(MC)

3-element Vector{String}:
 "d1cfe03 initial setup"
 "0c71009 initial tracked_parameters.toml"
 "0456eca (HEAD -> main) add files in `tracked_parameters/` to git"

MC.inputs

OrderedCollections.OrderedDict{Any, Any} with 4 entries:
  :main   => OrderedDict{Any, Any}(:PARM01=>OrderedDict{Symbol, Any}(:rigidLid=…
  :pkg    => OrderedDict{Any, Any}(:PACKAGES=>OrderedDict{Symbol, Any}())
  :eedata => OrderedDict{Any, Any}(:EEPARMS=>OrderedDict{Symbol, Any}(:nTx=>1, …
  :setup  => OrderedDict{Any, Any}(:main=>OrderedDict(:category=>"verification"…

MITgcm_launch(MC)
readdir(MC,"run")

295-element Vector{String}:
 "DRC.data"
 "DRC.meta"
 "DRF.data"
 "DRF.meta"
 "DXC.001.001.data"
 "DXC.001.001.meta"
 "DXC.001.002.data"
 "DXC.001.002.meta"
 "DXF.001.001.data"
 "DXF.001.001.meta"
 ⋮
 "pickup.ckptA.001.001.data"
 "pickup.ckptA.001.001.meta"
 "pickup.ckptA.001.002.data"
 "pickup.ckptA.001.002.meta"
 "pickup_somT.ckptA.001.001.data"
 "pickup_somT.ckptA.001.001.meta"
 "pickup_somT.ckptA.001.002.data"
 "pickup_somT.ckptA.001.002.meta"
 "tr_checklist"

rundir=joinpath(MC,"run")
sc=scan_rundir(rundir)
sc.params_grid

(usingCurvilinearGrid = false, nSy = 2, usingCartesianGrid = true, nPx = 1, sNy = 10, usingCylindricalGrid = false, Nx = 20, sNx = 20, nSx = 1, Nr = 1, Ny = 10, usingSphericalPolarGrid = false, nPy = 1)

Notebooks Listing

MITgcm_configurations.jl (code link); explore MITgcm configurations and their parameters.
MITgcm_scan_output.jl (code link) : scan run directory, standard output, read grid files, and vizualize.
MITgcm_run.jl (code link) : a detailed look into compiling and running the model.
MITgcm_worklow.jl (code link): build, setup, run, and plot for a chosen standard MITgcm configuration.

Note

The HS94* series of examples need to be run in sequence, as they rely on output from one another. This tutorial runs the Held and Suarez 94 benchmark with MITgcm on a cube sphere grid, and illustrates particle tracking in the Atmosphere using MeshArrays.jl and IndividualDisplacements.jl.

HS94_animation.jl (code link) : run hs94.cs-32x32x5 configuration, read output, interpolate, and plot maps.
HS94_particles.jl (code link) : compute particle trajectories from hs94.cs-32x32x5 output generated earlier.
HS94_Makie.jl (code link) : using Makie.jl instead of Plots.jl

Pluto Notebooks

Below are links to static html versions of the examples which one can open with a web browser.

If instead you wanted to run the notebooks using Pluto.jl, then you might proceed as follows:

open julia in terminal window
type the commands shown below at the Julia prompt
in web-browser, open one of the notebooks' code link using the Pluto interface.

using Pluto
Pluto.run(notebook="examples/MITgcm_configurations.jl")

Alternatively, you can run an example at the command line as, e.g.,

julia -e 'using Pluto
notebook="examples/MITgcm_configurations.jl"
Pluto.activate_notebook_environment(notebook)
using Pkg; Pkg.instantiate()
include(notebook)
'