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            = a20afe82-0f78-4b1e-9feb-18a2f0515772
  model         = MITgcm
  configuration = tutorial_held_suarez_cs
  run folder    = /tmp/a20afe82-0f78-4b1e-9feb-18a2f0515772
  log subfolder = /tmp/a20afe82-0f78-4b1e-9feb-18a2f0515772/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}:
 "4ab8bcc initial setup"
 "44128be initial tracked_parameters.toml"
 "10e4162 (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_run_dir 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)
• launch starts the model run

The scan_verification function provides a list of standard model configurations. Each one has a subfolder in MITgcm_path[2] which gets compiled using source code from MITgcm_path[1].

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 Drifters.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)

 MITgcm_system_check 
  name = advect_xy
  download = true
  complete = true
  mpi = false
  adj = false
  folder = /tmp/eb778a6f-591e-47e1-8780-bd15d7a6fe4d
  path_MITgcm = /home/runner/.julia/scratchspaces/124859b0-ceae-595e-8997-d05f6a7a8dfe/datadeps/mitgcmsmall/MITgcm
  path_verification = /home/runner/.julia/scratchspaces/124859b0-ceae-595e-8997-d05f6a7a8dfe/datadeps/mitgcmsmallverif/MITgcm/verification
  NETCDF_ROOT = /usr
  MPI_INC_DIR = /usr/lib/x86_64-linux-gnu/openmpi/include
  genmake_log = OrderedDict with 5 keys
  genmake_state = OrderedDict with 81 keys

• set_environment_variables_to_default() can be used to set NETCDF_ROOT and MPI_INC_DIR to default values.
• scan_build_dir can be used to inspect the build directory of an experiment.
• scan_run_dir can be used to inspect the run directory of an experiment.