Overview

MITgcm.jl allows the analysis of MITgcm results in Julia. It can also setup, build, and launch a chosen model configuration (MITgcm_config) from within julia.

Functionalities are documented in the coming sections, and in Examples, Notebooks.

Getting Started

Installing the latest version of MITgcm.jl with the built-in package manager is the recommended method.

using Pkg
Pkg.add("MITgcm")

Running MITgcm

Let's start running MITgcm interactively.

The first command defines a data structure, MITgcm_config, that we can then use from Julia. The setup command, by default, creates a folder in your tempdir() to run MITgcm.

using MITgcm
MC=MITgcm_config(configuration="tutorial_held_suarez_cs")
setup(MC)
show(MC)

  ID            = e114fd68-9339-4185-add4-0fc74f2e6a1e
  model         = MITgcm
  configuration = tutorial_held_suarez_cs
  run folder    = /tmp/e114fd68-9339-4185-add4-0fc74f2e6a1e
  log subfolder = /tmp/e114fd68-9339-4185-add4-0fc74f2e6a1e/log
  task(s)       = MITgcm_launch

After setup, the standard workflow is to call build and then MITgcm_launch.

Next we can use the log method to get a status report.

build(MC)
launch(MC)
log(MC)

3-element Vector{String}:
 "2916519 initial setup"
 "fcfee36 initial tracked_parameters.toml"
 "0936053 (HEAD -> main) add files in `tracked_parameters/` to git"

If we have a previous build of MITgcm for this then we can specify the file path as a parameter, :exe.

If :exe is not specified, or if no file is found at the specified path, build will attempt to build the model for us.

exe=joinpath(default_path(),"verification",MC.configuration,"build","mitgcmuv")
MC.inputs[:setup][:build][:exe]=exe

"/home/runner/.julia/scratchspaces/124859b0-ceae-595e-8997-d05f6a7a8dfe/datadeps/mitgcmsmall/MITgcm/verification/tutorial_held_suarez_cs/build/mitgcmuv"

Using Model Output

As MITgcm users, we often want to read and visualise model output from an earlier model run. To this end, MITgcm.jl provides methods to read the various file formats that MITgcm generates.

Read example:

T=read_mdsio(joinpath(MC,"run"),"T.0000276496")
size(T)

(192, 32, 20)

Plot example:

using CairoMakie

fig, ax, hm = heatmap(T[1:32,:,1])
ax.title="temperature"
Colorbar(fig[1, 2], hm)

fig

Main Features

• MITgcm File Formats
• MITgcm Configurations

MITgcm File Formats

MITgcm stores model output within a run/ folder, such as the standard STDOUT text files, and other file formats listed below. scan_rundir can be used to provide a summary of what's in the run/ folder. For more see:

• Standard Output (text)
• Input Files (text)
• MDS Files (binary output)
• MNC Files (netcdf output)
• Grid Files (binary or netcdf)
• Other Files

Grid variables are often needed for analysis. They can be read from file using either GridLoad_mdsio or GridLoad_mnc. This will return Γ.XC, Γ.YC, etc formated using MeshArrays.jl. See also GridLoad_native.

MITgcm Configurations

MITgcm.jl represents a model configuration using MITgcm_config. This data structure allows you take advantage of the ClimateModels.jl interface for example.

• setup prepares a run directory for the MITgcm_config
• build compiles the model (if needed)
• MITgcm_launch starts the model run

The verification_experiments function provides a list of standard model configurations. Each one has a subfolder in joinpath(default_path(),"verification") where the model often gets compiled.

Interactive notebooks can be found in the Examples section (and the examples/ subfolder). They demonstrate functionalities like plotting with Makie.jl and particle tracking with IndividualDisplacements.jl.

Troubleshooting

The system_check method will try running MITgcm and report back. If the result is negative for any particular item, you may want to consult the MITgcm documentation for more guidance.

using MITgcm
MITgcm.system_check(setenv=true)

4-element Vector{Any}:
 "MITgcm download" => true
    "run complete" => true
     "NETCDF_ROOT" => true
     "MPI_INC_DIR" => true

The set_environment_variables_to_default() method can be used to set NETCDF_ROOT and MPI_INC_DIR to default values.

The scan_rundir method can be used to inspect the run directory of an experiment.