Tutorials

Explanatory Jupyter notebooks

The following jupyter notebooks (formerly IPython) illustrate some analysis of MOM6 output with explanation. You can peruse the notebooks on GitHub by navigating through MOM6-examples.

You can also run the notebooks interactively yourself. You will need jupyter installed (we recommend using conda to obtain and manage python):

cd MOM6-examples/
jupyter notebook

And then open the URL posted in the output (if it doesn't open automatically).

Notebook title	Location	Notes
MOM6 cookbook	https://mom6-analysiscookbook.readthedocs.io/	A collection of explanatory python notebooks
Visualizing and animating sea surface height	MOM6-examples/ocean_only/double_gyre/	gist of notebook with images
Understanding native output	MOM6-examples/ocean_only/flow_downslope/	gist of notebook with images
Cheat sheet for using a Mosaic grid	gist.github.com	Illustrates the mosaic grid-spec used for defining input grids
Hydrographic section through Gibraltar Straits	gist.github.com	Uses some climate model output
Surface flux budgets in ocean-only mode	MOM6-examples/ocean_only/global_ALE/z/	Illustrates ways to combine surface flux diagnostics
Surface flux budgets in ice-ocean mode	MOM6-examples/ice_ocean_SIS/GOLD_SIS/	Illustrates ways to combine surface flux diagnostics
Choke point transports in OM4	MOM6-examples/ice_ocean_SIS2/OM4_025/	From early in OM4 development
Single column physics comparison	MOM6-examples/ocean_only/single_column/	Compares three boundary layer schemes for a BATS profile

Anatomy of an example directory

The directories corresponding to individual examples follow a common pattern of contents. Examples that have no binary input data typically look like:

tree MOM6-examples/ocean_only/benchmark/
MOM6-examples/ocean_only/benchmark/
|-- diag_table
|-- input.nml
|-- MOM_input
|-- MOM_memory.h
|-- MOM_override
|-- MOM_parameter_doc.all
|-- MOM_parameter_doc.layout
`-- MOM_parameter_doc.short

Of the above, only some files are read by the model while the rest are written. We record them in order version control the experiment as a whole, and to regression test the code.

Input file	i/o	Contents
input.nml	IN	Has the necessary fortran namelists for executing MOM6 and controlling non-MOM6 components of the code. This includes the list of MOM-style parameter files to read, usually "MOM_input" and "MOM_override".
MOM_input	IN	Contains all the necessary run-time parameters that define this experiment.
MOM_override	IN	Is usually blank except in cases where there are several variants on an example (e.g. with different coordinates).
diag_table	IN	List of diagnostics, used by FMS's diagnostic manager.
MOM_parameter_doc.all	OUT	Records all the run-time parameters that are not associated with the parallelization.
MOM_parameter_doc.short	OUT	Records all the non-default run-time parameters that are not associated with the parallelization.
MOM_parameter_doc.layout	OUT	Records all the run-time parameters that are associated with the parallelization. These parameters are computational and do not affect the numerical solution.
available_diags	OUT	a list of available diagnostics.
ocean.stats.*	OUT	are ascii files with a few key statistics/metrics used for bitwise regression testing by the core-MOM6 team. These files are version controlled in a separate "regressions" repository that is platform specific.

When you run the models you will so other files appear:

*.nc - Most diagnostics will be in netcdf files named in diag_table. There are a few others that are written to files such as "ocean_geometry.nc", "timestats.nc", "MOM_IC.nc", which are controlled by MOM6 rather than through the diagnostics manager.
ocean.stats, CPU_stats, - a few key statistics/metrics.
logfile.* -
RESTART/* - restart files. The model will fail with an error if the RESTART directory does not exist.
fort.*, exitcode, _read_error.nml - are written by FMS code and can usually be ignored.

Running and changing the "benchmark" test

As outlined in Getting started obtain an interactive shell on batch nodes:

msub -I -lsize=32,walltime=01:00:00

To run the benchmark test, cd to the benchmark directory and launch the executable:

cd ocean_only/benchmark/
mkdir -p RESTART
aprun -n 8 ../../build/intel/ocean_only/repro/MOM6

Altering the benchmark test

Domain size

The benchmark test case is an example of a regional ocean model with two (hypothetical) ocean basins connected via a channel. The idealized shape of the basins (i.e., ocean mask), topography and grids are generated at run-time so there is no need for input grid files. The initial conditions are also set at runtime.

The grid resolution is set at NIGLOBAL x NJGLOBAL = 360x180 (1/4 degree for the region in this test case). If desired, this can be changed via an input file (MOM_override) in the working directory. For example, to make the model 4 times bigger one could do this in the workdir:

cd ocean_only/benchmark/
cat << EOF > MOM_override 
#override NIGLOBAL = 720
#override NJGLOBAL = 360
EOF

Run time

The default total run time of this test is 2 days. This can be changed by adding the following lines to input.nml in the working directory:

cd ocean_only/benchmark/
cat << EOF >> input.nml
 &ocean_solo_nml
        months = 0
        days = 20 /
EOF

Restarts

The model will write the model state to the RESTART directory at the end of the run. To restart the model, copy the files from the RESTART directory to the INPUT directory. You also need to edit the input.nml file so that: