Case Setup (Case object) & Coupling

Once your grids are ready (see Grids and Bathymetry), the next step is creating a Case, CrocoDash’s orchestration object that ties your grid definition into CESM. Case(...) also decides, from your chosen compset, which additional forcings you’re on the hook for in Configure Forcings.

This notebook covers:

Section 1: the standalone-ocean case (Case(...) basics, compset reference table)
Section 2: how to discover what a compset requires, before calling configure_forcings
Section 3: coupling: sea ice (CICE6)
Section 4: coupling: biogeochemistry (MARBL)
Section 5: coupling: waves (WW3)

📖 CrocoDash case setup docs

Section 1: Create a Standalone-Ocean 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 Grid, Topo, and VGrid created in Grids and Bathymetry.
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-Runoff.

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

Begin by specifying the case name and the necessary directory paths. Ensure the CESM root directory points to your own local copy of CESM.

from pathlib import Path

# CESM case (experiment) name
casename = "panama-not"

# 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

Compset quick-reference¶

The compset argument controls which model components are active. Start with the ocean-only default and swap or add stubs as needed:

What you want	Change in `compset=`
Ocean only (default)	`compset="CR_JRA"`
+ Sea ice (CICE6)	change `CR_JRA` → `GR_JRA`
+ Biogeochemistry (MARBL)	add `%MARBL-BIO` to the MOM6 component, e.g. `MOM6%REGIONAL%MARBL-BIO`
+ Waves (WW3)	swap the stub `SWAV` → `WW3` in the long name
+ Data runoff (GLOFAS)	use `CR_JRA_GLOFAS`
+ Data runoff (JRA)	use `CR_JRA` with `DROF%JRA` (see Configure Forcings, Section 5)

For a deeper dive into each option:

CICE, BGC, or WW3: Sections 3–5 below
Runoff (GLOFAS / JRA / custom): Configure Forcings, Section 5

from CrocoDash.case import Case

case = Case(
    cesmroot = cesmroot,
    caseroot = caseroot,
    inputdir = inputdir,
    ocn_grid = grid,
    ocn_vgrid = vgrid,
    ocn_topo = topo,
    project = '<PROJECT>',
    override = True,
    machine = "derecho",
    compset = "CR_JRA" # This is the alias of the compset, the longname (which is printed when you run this command) is 1850_DATM%JRA_SLND_SICE_MOM6%REGIONAL_SROF_SGLC_SWAV. Feel free to use either way!
)

Section 2: Discover What a Compset Requires¶

Right after Case(...) succeeds, it prints a summary of any required forcing configurations you still owe for the compset you chose. These become your keyword arguments to case.configure_forcings(...) in the next step. A MARBL compset, for example, requires BGC, BGCIC (which needs marbl_ic_filepath), and BGCIronForcing. A DROF compset additionally requires Runoff, which takes no arguments of its own.

Two entries show up for nearly every case: conditions (required by any MOM6 compset -- it drives IC/OBC extraction, and its arguments all default on configure_forcings itself) and StreamYears (required by any DATM%JRA compset, no arguments).

What pulls in a configurator is the compset component, not the data product: any DROF compset requires Runoff whether or not you use %GLOFAS.

You don’t have to build a real Case to see this. The same registry the constructor calls is available standalone, keyed off any compset long name string:

from CrocoDash.forcing.base import ForcingConfigRegistry


def print_required(compset):
    print(compset)
    for config_class in ForcingConfigRegistry.find_required_configurators(compset):
        user_args = ForcingConfigRegistry.get_user_args(config_class)
        print(f"  Required: {config_class.name}  (needs: {user_args or 'no arguments'})")


# Section 4 below builds a Case with this compset (MARBL, no active runoff):
print_required("1850_DATM%NYF_SLND_SICE_MOM6%MARBL-BIO%REGIONAL_SROF_SGLC_SWAV")

# Switching SROF to DROF adds a Runoff configurator to the required list:
print_required("1850_DATM%NYF_SLND_SICE_MOM6%MARBL-BIO%REGIONAL_DROF%GLOFAS_SGLC_SWAV")

On a live Case, case.compset_lname gives you the resolved long name CrocoDash already validated against, so you can run the same check without retyping it:

required = ForcingConfigRegistry.find_required_configurators(case.compset_lname)

See Configure Forcings for how each required configurator maps onto a configure_forcings() keyword. Two more introspection helpers worth knowing: ForcingConfigRegistry.find_valid_configurators(compset) (same pattern as find_required_configurators, but returns everything compatible with the compset, not just what’s required), and, per configurator class rather than on the registry itself, configurator_cls.validate_compset_compatibility(compset) / ForcingConfigRegistry.return_missing_inputs(configurator_cls, inputs_dict) (checked against a specific configurator class + an inputs dict, not a plain compset string).

Section 3: Coupling: Sea Ice (CICE6)¶

Swap the stub SICE (stub sea ice) for CICE in the compset. Everything else, grid, topo, vgrid, forcings, is identical to the standalone run.

from CrocoDash.case import Case

case = Case(
    cesmroot=cesmroot,
    caseroot=caseroot,
    inputdir=inputdir,
    ocn_grid=grid,
    ocn_vgrid=vgrid,
    ocn_topo=topo,
    project="<PROJECT>",
    override=True,
    machine="derecho",
    compset="GR_JRA",  # GR_JRA = 1850_DATM%JRA_SLND_CICE_MOM6%REGIONAL_SROF_SGLC_SWAV
)

Optional: Warm start from CICE restart files¶

After a first run you can use CICE restart files as the ice initial condition instead of CICE’s default (its own latitude/SST-based initialization). This gives a more realistic sea-ice state at the start of subsequent runs.

Find restart files in your archive: <caseroot>/archive/rest/<year>/, look for *.cice.r.*.nc. If unsure of the archive path, run ./xmlquery DOUT_S_ROOT in the case directory.
Copy the file to your run directory: cp <restart_file> <run_dir>/.
Open user_nl_cice and change its ice_ic line to ice_ic = "<restart_filename>". CrocoDash’s CICE configuration already writes an ice_ic line there, so edit that one rather than adding a second.

Section 4: Coupling: Biogeochemistry (MARBL)¶

MARBL (the Marine Biogeochemistry Library) is bundled with CESM. Activating it requires:

A compset that includes MOM6%REGIONAL%MARBL-BIO.
A MARBL global initial-condition file.
Passing BGC-specific kwargs to configure_forcings (see Configure Forcings, Section 6).

Optionally, combine with river nutrients by also enabling GLOFAS runoff.

from CrocoDash.case import Case

case = Case(
    cesmroot=cesmroot,
    caseroot=caseroot,
    inputdir=inputdir,
    ocn_grid=grid,
    ocn_vgrid=vgrid,
    ocn_topo=topo,
    project="<PROJECT>",
    override=True,
    machine="derecho",
    compset="CR1850MARBL_JRA",
)

Once this Case exists, rerun Section 2’s discovery check against case.compset_lname to confirm exactly which configure_forcings kwargs you owe, for this compset that’s marbl_ic_filepath (matching the first print_required(...) call above, and the printed report Case(...) already gave you).

Section 5: Coupling: Waves (WW3)¶

Swap the stub SWAV (stub waves) for WW3 in the compset. The CROCODILE CESM fork ships regional wave-coupled aliases, CWR_JRA (ocean + waves) and GWR_JRA (ocean + CICE + waves), plus _GLOFAS and MARBL variants. CW_JRA and GW_JRA are the global MOM6 ones, so don’t reach for those.

The example below passes a long name directly instead, because it uses NYF rather than JRA data atmosphere -- any long name works wherever an alias does:

from CrocoDash.case import Case

case = Case(
    cesmroot=cesmroot,
    caseroot=caseroot,
    inputdir=inputdir,
    ocn_grid=grid,
    ocn_vgrid=vgrid,
    ocn_topo=topo,
    project="<PROJECT>",
    override=True,
    machine="derecho",
    compset="1850_DATM%NYF_SLND_SICE_MOM6%REGIONAL_SROF_SGLC_WW3_SESP",
)
print("WW3 in compset:", case.ww3_in_compset)

SESP on the end is CESM’s stub external-system-processing component, unrelated to waves, it’s simply what a compset long name carries after an active WAV component. Dropping it (..._SGLC_WW3) also works.

With WW3 active, Case(...) writes WW3’s grid-preprocessor input files into <inputdir>/wav/, beside the MOM6 grid files in <inputdir>/ocn/: ww3_grid.inp plus <grid_name>_x.inp, _y.inp, _bottom.inp, and _mapsta.inp, derived from the same Topo you already built. WW3’s mod_def step reads these before runtime, so the wave model runs on your ocean grid and land/sea mask, with no separate wave grid to build.

case.ww3_in_compset is the same check CrocoDash uses internally, and is worth printing if you’re unsure whether your long name actually activated the wave model.

Wave forcing itself, boundary spectra flowing in through the open boundaries, is covered in Configure Forcings, Section 8.

Next steps¶

Continue to Configure Forcings to fill in the BGC/runoff arguments this compset requires, or jump to Process Forcings once configured.