Running CrocoDash from the CLI

CrocoDash cases can be set up entirely from the command line using a YAML config file — no Python scripting required.

The workflow is three steps:

# 1. Get a starter config
crocodash template --output my_case.yaml

# 2. Edit it (fill in paths, domain, compset, etc.)
vim my_case.yaml

# 3. Create the case
crocodash create --config my_case.yaml

Add --machine derecho to template to pre-fill known dataset paths for Derecho/GLADE:

crocodash template --output my_case.yaml --machine derecho

Starter config¶

The template gives you a fully annotated YAML with all available options:

starter_case.yaml

# CrocoDash starter case config
# Edit this file, then run: crocodash create --config <this_file>
# Tip: run `crocodash dump --caseroot PATH` on an existing case to generate a config.

# ── Grid ─────────────────────────────────────────────────────────────────────
# Option A (recommended for new cases): define the domain by extent and resolution
grid:
  lenx: 3.0          # domain width  (degrees longitude)
  leny: 3.0          # domain height (degrees latitude)
  xstart: 278.0      # western edge longitude
  ystart: 7.0        # southern edge latitude
  resolution: 0.1    # grid resolution in degrees  (or use nx/ny instead)
  name: my_case

# Option B: load an existing supergrid file
# grid:
#   supergrid_path: /path/to/ocean_hgrid.nc
#   name: my_case

# ── Bathymetry ────────────────────────────────────────────────────────────────
topo:
  min_depth: 9.5
  source:
    type: flat         # flat | dataset | from_file
    depth: 5000.0      # constant ocean depth in metres  (flat only)

    # type: dataset    # interpolate from a bathymetry file (e.g. GEBCO)
    # bathymetry_path: <GEBCO>
    # longitude_coordinate_name: lon   # default
    # latitude_coordinate_name: lat    # default
    # vertical_coordinate_name: elevation  # default

    # type: from_file  # load a pre-computed topo file
    # topo_file_path: /path/to/ocean_topog.nc

# ── Vertical grid ─────────────────────────────────────────────────────────────
vgrid:
  type: uniform      # uniform | hyperbolic | from_file
  nk: 75
  # depth omitted → uses topo.max_depth automatically

  # type: hyperbolic  # surface-intensified layers
  # nk: 75
  # ratio: 10.0       # ratio of thickest to thinnest layer

  # type: from_file
  # filename: /path/to/vgrid.nc

# ── CESM case ─────────────────────────────────────────────────────────────────
case:
  cesmroot: <CESM>
  caseroot: <casedir>/my_case
  inputdir: <inputdir>/my_case
  compset: "1850_DATM%JRA_SLND_SICE_MOM6%REGIONAL_SROF_SGLC_SWAV"
  machine: derecho
  project: YOUR_PROJECT    # HPC allocation (e.g. ncgd0011)
  atm_grid_name: TL319     # atmospheric grid; TL319 ≈ 0.5° resolution

  # optional CESM tuning:
  # rof_grid_name: null
  # ninst: 1
  # ntasks_ocn: null
  # job_queue: main
  # job_wallclock_time: "01:00:00"

# ── Forcings ───────────────────────────────────────────────────────
forcings:
  date_range: ["2020-01-01 00:00:00", "2020-12-31 00:00:00"]
  boundaries: [north, south, east, west]
  product_name: GLORYS
  function_name: get_glorys_data_from_rda

  # Tidal forcing (optional):
  # tidal_constituents: [M2, S2, K1, O1]
  # tpxo_elevation_filepath: <TPXO_H>
  # tpxo_velocity_filepath: <TPXO_U>

  # BGC initial conditions (optional):
  # marbl_ic_filepath: <MARBL_IC>

Round-tripping an existing case¶

If you already have a CrocoDash case and want to reproduce or modify it, dump reconstructs the YAML from the case’s state files:

crocodash dump --caseroot /path/to/my_case > my_case.yaml

Edit the output and re-run with crocodash create --config my_case.yaml --override.

All subcommands¶

Command	Purpose
`crocodash template`	Write a starter config (`.yaml`), notebook (`.ipynb`), or script (`.py`)
`crocodash create`	Create a case from a YAML config
`crocodash dump`	Reconstruct YAML from an existing case
`crocodash bundle`	Package a case for sharing
`crocodash fork`	Create a new case from a bundle with guided editing
`crocodash duplicate`	Copy an existing case to a new location