cesm-mom6-diags

Template scripts and Jupyter notebooks for running ocean diagnostics on CESM MOM6 simulations, including climatologies, transports, MOC, T/S biases, and more on NCAR systems.

Diagnostics are built on mom6-tools. See the mom6-tools documentation for detailed guidance.

Overview

The workflow has two steps:

1. Run diagnostic scripts (make diags) — submits PBS jobs to Casper that process model output into NetCDF files.
2. Build HTML report (make html) — runs Jupyter notebooks via papermill and builds a Jupyter Book website, then deploys it to the CGD web server.

Setup

1. Configure diag_config.yml

Edit diag_config.yml to point to your case. Key fields:

Case:
  CASEROOT: /path/to/your/case/
  OCN_DIAG_ROOT: /path/to/output/ncfiles/
  SNAME: "my_case_short_name"

Avg:
  start_date: 'YYYY-01-01'
  end_date:   'YYYY-01-01'

The Transports section lists ocean sections where volume transports are computed. Edit or extend this list as needed.

2. Configure oce_cat in diag_config.yml (optional)

The latest version of reference-datasets.yml is available at (if you have access)

/glade/campaign/cgd/oce/projects/CESM-MOM6/diagnostics/oce-catalogs/

And oce_cat points to this directory by default:

oce_cat: /glade/campaign/cgd/oce/projects/CESM-MOM6/diagnostics/oce-catalogs/reference-datasets.yml

If you don't have access, you can download it from oce-catalogs, or you can use your own reference-datasets.yml file.

3. Configure dask-jobqueue

mom6-tools has migrated away from NCAR-jobqueue to dask-jobqueue. The relevant configurations are in the jobqueue section of diag_config.yml:

jobqueue:
  cluster_class: 'PBSCluster'
  account: <account>
  cores: 1
  memory: '16GB'
  processes: 1
  interface: 'ext' # for derecho, interface: 'ib0' # for casper, interface: 'ext'
  queue: 'casper' # for derecho, queue: 'develop' # for casper, queue: 'casper'
  walltime: '02:00:00'
  resource_spec: 'select=1:ncpus=1:mem=16GB'
  log_directory: '/glade/derecho/scratch/<username>/dask/casper/logs'
  local_directory: '/glade/derecho/scratch/<username>/dask/casper/local-dir'

You should set your account number and user name here, and change the memory request and walltime if needed.

Also update the PBS account (#PBS -A) in all scripts/*.sh files and in notebooks/run_notebooks.sh if needed.

4. Configure notebooks/run_notebooks.sh

Set the CASE and COMPSET variables at the top of notebooks/run_notebooks.sh to match your simulation:

CASE="your.case.name"
COMPSET=BLT1850   # BLT1850 or GIAF

5. Activate the conda environment

The scripts expect the mom6-tools conda environment:

conda activate mom6-tools

This is done automatically when you run scripts and notebooks. You need to activate mom6-tools manually only if you want to clear all notebook outputs (make clean_notebooks).

Usage

Step 1 — Run diagnostic scripts

make diags

This runs run_scripts.sh, which submits the following PBS jobs to Casper:

Script	Description
climo_native.sh	Climatology on native MOM6 grid
climo_z.sh	Climatology on z-level grid
basin_reductions.sh	Basin-mean reductions
moc.sh	Meridional overturning circulation (z)
moc_sigma2.sh	MOC in sigma-2 density coordinates
pht.sh	Poleward heat transport
aaiw_pv.sh	AAIW potential vorticity
enso.sh	ENSO indices
transports.sh	Volume transports through key sections
surface.sh	Surface fields
equatorial.sh	Equatorial diagnostics
ts_levels.sh	T/S at depth levels
stats.sh	Global ocean statistics
drift_thetao.sh	Temperature drift
rms_thetao.sh	Temperature RMS error
drift_so.sh	Salinity drift
rms_so.sh	Salinity RMS error
tao.sh	TAO mooring diagnostics
dwbc.sh	Deep western boundary current

After jobs complete, copy the output NetCDF files to your OCN_DIAG_ROOT:

# Reminder also printed by make diags:
cp -r ncfiles/ $OCN_DIAG_ROOT

Step 2 — Build HTML report

make html

This submits notebooks/run_notebooks.sh to Casper, which:

1. Generates the table of contents and intro page.
2. Executes all notebooks with papermill.
3. Builds a Jupyter Book from the notebooks.
4. Deploys the HTML output to tungsten.cgd.ucar.edu under /project/diagnostics/external/<COMPSET>/<CASE>/ocn/.

Notebooks

Notebook	Description
ts_biases.ipynb	Temperature and salinity biases
moc.ipynb	Meridional overturning circulation
pht.ipynb	Poleward heat transport
mld.ipynb	Mixed layer depth
bld.ipynb	Boundary layer depth
transports.ipynb	Volume transports
equatorial.ipynb	Equatorial sections
ocean_stats.ipynb	Global ocean statistics
enso.ipynb	ENSO
aaiw_pv.ipynb	AAIW potential vorticity
ssh.ipynb	Sea surface height
model_26N_transect.ipynb	Mean meridional velocity at 26.5N

Utility targets

make clean_notebooks   # Clear all notebook outputs in place
make clean             # Remove all generated files and restore notebooks from git

Dependencies

• mom6-tools
• papermill
• jupyter-book
• oce-catalogs — reference ocean observational datasets
• PBS/Casper (NCAR HPC)