2. Case Setup (Case object)

Once you have your grids ready, the next step is creating a Case object. The Case is CrocoDash’s main orchestration object: it wraps a CESM regional MOM6 case, ties your grid definition into CESM’s machinery, and gives you the three verbs that drive the rest of the workflow:

1. Instantiate Case(...) — sets up the case directory and registers your grid with CESM

2. case.configure_forcings(...) — declares which forcings your case needs (Step 3a)

3. case.process_forcings(...) — generates the forcing files (Step 3b)

This page covers step 2. Steps 3a and 3b have their own pages.

Minimal example

import CrocoDash as cd

case = cd.Case(
    cesmroot="/path/to/CESM",
    caseroot="/path/to/your/case",
    inputdir="/path/to/your/inputdata",
    compset="CR_JRA",
    ocn_grid=grid,
    ocn_topo=topo,
    ocn_vgrid=vgrid,
    machine="derecho",
    project="UCSG0000",
)

That one call:

• Initialises VisualCaseGen and the CESM CIME interface

• Validates your compset, grid, bathymetry, and vertical grid against the regional-MOM6 constraints

• Creates the case directory via create_newcase

• Writes your grid/topo/vgrid files to inputdir

• Applies queue/wallclock/task-count xmlchange settings

• Prints a summary of any required forcing configurations you still owe (these become your arguments to configure_forcings in step 3a)

Picking a compset

Not sure which compset= to pass? See the regional compsets table in Compsets & Inputs for the aliases CrocoDash ships with (CR_JRA, CR1850MARBL_JRA_GLOFAS, GR_JRA, …) and which model components each activates.

Required arguments

Argument	Type	Meaning
cesmroot	path	Root of your existing CESM checkout. Must already exist.
caseroot	path	Where the CESM case directory will be created. Must NOT already exist (unless override=True).
inputdir	path	Where CrocoDash writes grid + forcing input files. Must NOT already exist (unless override=True).
compset	str	Either an alias (e.g. "CR_JRA") or a full long name. See Compsets & Inputs.
ocn_grid	Grid	Your horizontal grid from Step 1.
ocn_topo	Topo	Your bathymetry from Step 1.
ocn_vgrid	VGrid	Your vertical grid from Step 1.

Useful optional arguments

Argument	Default	Notes
machine	None	CESM machine name (e.g. "derecho"). Required — Case raises a ValueError if it can’t be determined.
project	None	Project/account code. Required on machines that use accounting.
atm_grid_name	"TL319"	Atmosphere grid (data-atmosphere resolution).
rof_grid_name	None	Runoff grid. Auto-inferred from compset; required only when multiple options are available.
ntasks_ocn	VCG default	Number of MPI tasks for MOM6.
job_queue	CESM default	Batch queue.
job_wallclock_time	CESM default	Wallclock (hh:mm:ss).
ninst	1	Number of model instances (ensemble size).
override	False	Allow overwriting an existing caseroot / inputdir.

What Case.__init__ does, in order

        flowchart TD
    A["Case(...)"] --> B["Initialize VisualCaseGen + CIME"]
    B --> C["Resolve compset alias → longname"]
    C --> D["Validate arguments<br/>(Case.init_args_check)"]
    D --> E["Configure VCG variables<br/>(compset, grid, launch)"]
    E --> F["Write grid input files<br/>(hgrid, topo, vgrid, mesh)"]
    F --> G["create_newcase"]
    G --> H["Apply ntasks / queue / wallclock<br/>via xmlchange"]
    H --> I["Report required<br/>forcing configurators"]
    

You don’t need to call any of these individually — instantiating Case runs the whole sequence.

Reading the “required configurators” message

After Case(...) succeeds, you’ll see something like this for a compset with MARBL BGC and GLOFAS runoff (e.g. CR1850MARBL_JRA_GLOFAS):

The following additional configuration options are required to run and must be
provided with any listed arguments in configure_forcings:
  - BGC: no arguments
  - BGCIC: marbl_ic_filepath
  - Runoff: no arguments

Each line is one configurator class plus the keyword arguments you’ll need to pass to case.configure_forcings(...) in the next step (arguments starting with case_ are filled in automatically and never appear here). Note that configurators like tides aren’t tied to any compset component, so they’re never “required” — they’re optional and you add them whenever you want tidal forcing. Standalone compsets with no BGC/CICE/runoff component (e.g. CR_JRA) print nothing here at all. See Configure Forcings for the full story.

You can reproduce this list at any time:

from CrocoDash.forcing_configurations import ForcingConfigRegistry
required = ForcingConfigRegistry.find_required_configurators(case.compset_lname)

Compset properties on the Case

Case exposes a few convenience properties derived from your compset:

Property	True when…
case.cice_in_compset	"CICE" appears in the compset longname
case.runoff_in_compset	"SROF" is not in the compset longname (i.e. active/data runoff)
case.bgc_in_compset	"%MARBL" appears in the compset longname

These are handy for branching in user scripts and are also what the forcing configurators use internally to decide which configurators are compatible.

Common pitfalls

• Given caseroot ... already exists! — pass override=True or pick a fresh path. override=True is safe for iteration but will remove the prior case directory.

• compset must be a valid CESM compset long name or alias. — aliases are resolved against your CESM checkout’s compset list. If the alias isn’t in the available compsets, you either have the wrong cesmroot or your CESM checkout doesn’t include the CROCODILE compset fork.

• Only MOM6-based compsets are supported. CrocoDash enforces MOM6, SLND, SGLC, and SWAV in the compset longname. Active land/glacier/wave models are not supported.

• Machine requires a project. If your machine has accounting, project= is not optional.

Next steps

• 3a. Configure Forcings — declare the data your case needs

• 3b. Process Forcings — generate the forcing files

• Compsets & Inputs — reference for compset aliases and MOM6 parameter tuning

See also

• Submodule API Usage — exactly which VisualCaseGen/regional-mom6 entry points Case calls