Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Basic CrocoDash Tutorial: Ocean + Waves + Sea Ice

Set up a regional MOM6 run coupled to the WW3 wave model and CICE sea ice model.

What’s different from the ocean-wave tutorial:

  1. Compset: GWR_JRA instead of CWR_JRA, which adds CICE.

  2. Sea Ice Outflow conditions

  3. Sea Ice initial and boundary conditions

Recall that a typical workflow of utilizing CrocoDash consists of four main steps:

  1. Generate a regional MOM6 domain.

  2. Create the CESM case.

  3. Prepare forcing data.

  4. Build and run the case.

The first step in running CrocoDash is installing it! Please go to https://crocodile-cesm.github.io/CrocoDash/latest/installation.html to install CrocoDash!

SECTION 1: Generate a regional MOM6 domain

We begin by defining a regional MOM6 domain using CrocoDash. To do so, we first generate a horizontal grid. We then generate the topography by remapping an existing bathymetric dataset to our horizontal grid. Finally, we define a vertical grid.

Step 1.1: Horizontal Grid

📖 Grid documentation

# from CrocoDash.grid import Grid

# grid = Grid(
#  resolution = 1/8, # in degrees
#  xstart = 177, # min longitude in [0, 360]
#  lenx = 27.0, # longitude extent in degrees
#  ystart = 55.0, # min latitude in [-90, 90]
#  leny = 12.0, # latitude extent in degrees
#  name = "bering",
# )

Step 1.2: Topography

# from CrocoDash.topo import Topo

# topo = Topo(
#     grid = grid,
#     min_depth = 9.5, # in meters
# )
#from pathlib import Path

#bathymetry_path= Path("<GEBCO_LOWRES>")
# The GEBCO bathymetry path on Derecho is: <GEBCO>

#if not bathymetry_path.exists():
#    raise FileNotFoundError("Bathymetry file not found, please replace with path to bathymetry file")

#topo.set_from_dataset(
#    bathymetry_path = bathymetry_path,
#    longitude_coordinate_name="lon",
#    latitude_coordinate_name="lat",
#    vertical_coordinate_name="elevation",
#    depth_method = "xesmf",
#    mask_method = "dataset"
#)
# The grid and topography are the same as the ocean-wave tutorial (tutorial-ocn-wav.ipynb),
# so read them in from that tutorial's input directory. Run that tutorial first.

from pathlib import Path
from CrocoDash.topo import Topo
from CrocoDash.grid import Grid

ocn_wav_dir = Path("<inputdir>") / "bering_ocn_wav.001" / "ocn"

grid = Grid.from_supergrid(
    str(next(ocn_wav_dir.glob("ocean_hgrid_bering_*.nc"))), # path to the regional supergrid
    name = "bering",
)

bathymetry_path = next(ocn_wav_dir.glob("ocean_topog_bering_*.nc"))

topo = Topo.from_topo_file(
    grid=grid,
    topo_file_path=bathymetry_path,
    min_depth=9.5,
)
topo.basintmask.plot(size=4, aspect = grid.nx / grid.ny)
#topo.keep_largest_basin()
#topo.basintmask.plot(size=4, aspect = grid.nx / grid.ny)
## Optionally, uncomment the below lines to further modify the topography interactively
#%matplotlib ipympl
#from CrocoDash.topo_editor import TopoEditor
#TopoEditor(topo)

Step 1.3: Vertical Grid

📖 Grid documentation

#from CrocoDash.vgrid import VGrid

#vgrid  = VGrid.hyperbolic(
#    nk = 32, # number of vertical levels
#    depth = topo.max_depth,
#    ratio=50.0 # target ratio of top to bottom layer thicknesses
#)
from CrocoDash.vgrid import VGrid

vgrid = VGrid.from_file(str(next(ocn_wav_dir.glob("ocean_vgrid_bering_*.nc"))))
import matplotlib.pyplot as plt
plt.close()
# Create the plot
for depth in vgrid.zi:
    plt.axhline(y=depth, linestyle='-')  # Horizontal lines

plt.ylim(max(vgrid.zi) + 10, min(vgrid.zi) - 10)  # Invert y-axis so deeper values go down
plt.ylabel("Depth")
plt.title("Vertical Grid")
plt.show()

SECTION 2: Create the CESM case

After generating the MOM6 domain, the next step is to create a CESM case using CrocoDash. This process is straightforward and involves instantiating the CrocoDash Case object. The Case object requires the following inputs:

  • CESM Source Directory: A local path to a compatible CESM source copy. For the workshop, this is the CESM/ folder of your CROCODILEworkspace install.

  • Case Name: A unique name for the CESM case. For the workshop, cases go in the croc_cases/ folder of your CROCODILEworkspace install, in a folder named after the case.

  • Input Directory: The directory where all necessary input files will be written. You don’t need to put anything in it: CrocoDash creates it and fills it with the grid, bathymetry and forcing files automatically. For the workshop, it’s the croc_input/ folder of your CROCODILEworkspace install.

  • MOM6 Domain Objects: The horizontal grid, topography, and vertical grid created in the previous section.

  • Project ID: (Optional) A project ID, if required by the machine. For the workshop, use UCGD0009.

  • Compset: The set of models to be used in the Case. Standalone Ocean, Ocean-BGC, Ocean-Seaice, Ocean-Wave, etc.

If you installed this notebook with CROCODILEworkspace, these paths and the project ID are already filled in for you in the code below.

Step 2.1: Specify case name and directories:

Begin by specifying the case name and the necessary directory paths. Ensure the CESM root directory points to your own local copy of CESM. Below is an example setup:

from pathlib import Path

# CESM case (experiment) name
casename = "bering_ocn_wav_ice.001"

# CESM source root (Update this path accordingly!!!)
cesmroot ="<CESM>"

# Place where all your input files go 
inputdir = Path("<inputdir>") / casename
    
# CESM case directory
caseroot = Path("<casedir>") / casename

Step 2.2: Create the Case

To create the CESM case, instantiate the Case object as shown below. This will automatically set up the CESM case based on the provided inputs: The cesmroot argument specifies the path to your local CESM source directory. The caseroot argument defines the directory where the case will be created. CrocoDash will handle all necessary namelist modifications and XML changes to align with the MOM6 domain objects generated earlier. The job_queue and job_wallclock_time arguments set the PBS queue and the walltime (hh:mm:ss) CESM requests when you submit the run; leave them out to use the machine defaults.

📖 Case documentation

Compset quick-reference

The compset argument controls which model components are active.

What you wantChange in compset=
Ocean only (default)compset="CR_JRA"
+ Waves (WW3)compset="CWR_JRA"
+ Sea ice (CICE6)compset="GWR_JRA"
+ Biogeochemistry (MARBL)add %MARBL-BIO to the MOM6 component, e.g. MOM6%REGIONAL%MARBL-BIO
+ Data runoff (GLOFAS)use CWR_JRA_GLOFAS
+ Data runoff (JRA)use CWR_JRA with DROF%JRA (see runoff notebook)

Note that in this notebook, we are switching from "CR_JRA" to "GWR_JRA" to enable WW3 and CICE.

For a deeper dive into each option:

from CrocoDash.case import Case

case = Case(
    cesmroot = cesmroot,
    caseroot = caseroot,
    inputdir = inputdir,
    ocn_grid = grid,
    ocn_vgrid = vgrid,
    ocn_topo = topo,
    project = '<PROJECT>', # Enter Project ID for PBS Queue
    job_queue = "<JOB_QUEUE>", # PBS queue the run is submitted to
    job_wallclock_time = "<WALLCLOCK_1H>", # hh:mm:ss walltime requested for the run
    override = True,
    machine = "<MACHINE>",
    compset = "GWR_JRA"
)

Section 3: Prepare ocean, wave, and sea ice forcing data

We need to cut out our ocean and waves forcing. The package expects an initial condition and one time-dependent segment per non-land boundary. Naming convention is "east_unprocessed" for segments and "ic_unprocessed" for the initial condition.

In this notebook, we are forcing with the Copernicus Marine “Glorys” reanalysis dataset. There’s a function in the CrocoDash package, called configure_forcings, that generates a bash script to download the correct boundary forcing files for your experiment. First, you will need to create an account with Copernicus, and then call copernicusmarine login to set up your login details on your machine. Then you can run the get_glorys_data.sh bash script.

Step 3.1 Configure Initial Conditions and Forcings

📖 Configure forcings docs · Available datasets

case.configure_forcings(
    date_range = ["2020-03-01 00:00:00", "2020-04-01 00:00:00"],
    boundaries=["south","north","west"],
    product_name = "GLORYS",
    function_name="get_glorys_data_from_rda",
    ww3_obc_product_name='CESM-WW3-JRA',
    ww3_obc_function_name="get_cesm_ww3_jra_spectra",        
    restore_ice=True,
    cice_product_name="cice_restart",
    cice_function_name="get_cice_restart_subset",
    cice_function_args={
        "restart_path": "/glade/u/home/dbailey/b.e30_alpha09b.B1850C_MTso.ne30_t233_wgx3.360.cice.r.0201-01-01-00000.nc",
        "grid_path": "/glade/campaign/cesm/community/omwg/grids/tx2_3v3_grid.nc",
    },        
)

Notice above that we add two new arguments, "ww3_obc_product_name" and "ww3_obc_function_name" for wave boundary conditions. Additionally, we add four arguments for sea ice. restore_ice=True together with cice_product_name and cice_function_name turns on CICE boundary restoring; you must give all three or none. The cice_restart product regrids a global CICE restart (restart_path and its grid file grid_path) onto our domain with a one-cell border. That single file is both CICE’s initial condition and the state the boundary cells are restored toward.

Step 3.3: Process forcing data

In this final step, we call the process_forcings method of CrocoDash to cut out and interpolate the initial condition as well as all boundaries. CrocoDash also updates MOM6/WW3 runtime parameters and CESM xml variables accordingly.

case.process_forcings()
print("You can now build and run your case at",caseroot)

Section 4: Build and run the case

After completing the previous steps, you are ready to build and run your CESM case. Begin by navigating to the case root directory specified during the case creation. Before proceeding, review the user_nl_mom file located in the case directory. This file contains MOM6 parameter settings that were automatically generated by CrocoDash. Carefully examine these parameters and make any necessary adjustments to fine-tune the model for your specific requirements. While CrocoDash aims to provide a solid starting point, further tuning and adjustments are typically necessary to improve the model for your use case.

Once you have reviewed and modified the parameters as needed, you can build and execute the case using the following commands. CESM cases must be built and submitted on the machine you passed as machine when creating the Case. For the workshop, that’s Derecho (not Casper), so the commands start by logging in to Derecho and going to the case directory:

ssh derecho
cd <casedir>/bering_ocn_wav_ice.001
qcmd -A <PROJECT> -- ./case.build
./case.submit
CROCOGallery
Ocean + Waves
CROCOGallery
Grids (Horizontal · Vertical)