Command Line Interface

Command Line Interface#

CrocoDash ships a crocodash command (installed automatically with pip install -e .) that lets you run the full case setup workflow from a YAML config file and inspect or share existing cases — no Python scripting required.

Quick reference#

crocodash create   --config mycase.yaml [--override]
crocodash dump     --caseroot /path/to/case
crocodash bundle   --caseroot /path/to/case --output-dir /path/to/bundle_dir ...
crocodash fork     --bundle /path/to/bundle --caseroot ... --inputdir ... --cesmroot ... --machine ... --project ...
crocodash duplicate --source /path/to/case --case /path/to/new_case --inputdir /path/to/new_inputdir

crocodash create#

Creates a new CrocoDash case end-to-end from a YAML config file. Equivalent to calling recipe.create_case_from_yaml().

crocodash create --config mycase.yaml
crocodash create --config mycase.yaml --override   # overwrite existing caseroot/inputdir

YAML config schema#

# --- Horizontal grid ---
grid:
  lenx: 10.0           # domain width in degrees
  leny: 10.0           # domain height in degrees
  xstart: -60.0        # western edge longitude
  ystart: 30.0         # southern edge latitude
  resolution: 1.0      # degrees per cell (or use nx/ny instead)
  name: "mygrid"

# --- Bathymetry ---
topo:
  min_depth: 10.0      # columns shallower than this are masked
  source:
    type: "flat"           # flat | dataset | from_file
    depth: 1000.0          # for type: flat — constant depth in metres

    # type: dataset — interpolate from a real bathymetry file (e.g. GEBCO)
    # bathymetry_path: "/path/to/gebco.nc"
    # longitude_coordinate_name: "lon"
    # latitude_coordinate_name: "lat"
    # vertical_coordinate_name: "elevation"
    # is_input_positive_below_msl: false
    # fill_channels: false

    # type: from_file — reuse an existing topog.nc
    # topo_file_path: "/path/to/ocean_topog.nc"

# --- Vertical grid ---
vgrid:
  type: "uniform"      # uniform | hyperbolic | from_file
  nk: 10               # number of layers
  # depth omitted → uses topo.max_depth automatically
  name: "myvgrid"

  # type: hyperbolic — surface-intensified levels
  # nk: 75
  # depth: 5000.0
  # ratio: 20.0

  # type: from_file — reuse an existing vgrid.nc
  # filename: "/path/to/ocean_vgrid.nc"

# --- CESM case ---
case:
  cesmroot: "/path/to/CROCESM"
  caseroot: "/path/to/cases/mycase"
  inputdir:  "/path/to/croc_input/mycase"
  compset:   "CR_JRA"          # alias or full long name
  machine:   "derecho"
  project:   "NCGD0011"
  atm_grid_name: "TL319"       # optional, default TL319

# --- Forcings (required) ---
forcings:
  date_range: ["2020-01-01 00:00:00", "2020-02-01 00:00:00"]
  boundaries: ["south", "east", "west"]
  product_name: "GLORYS"
  function_name: "get_glorys_data_from_rda"

  # Any extra kwargs are forwarded directly to configure_forcings:
  # tidal_constituents: ["M2", "S2"]
  # tpxo_elevation_filepath: "/path/to/TPXO_elevation.nc"
  # tpxo_velocity_filepath:  "/path/to/TPXO_velocity.nc"

After create completes the caseroot contains a crocodash_state.json recording all construction parameters, and inputdir/extract_forcings/config.json recording the forcing setup. These files are the source of truth for dump, bundle, and fork.

crocodash dump#

Prints a YAML representation of an existing case to stdout. The output can be saved, edited, and passed back to create — making dump the exact inverse of create.

# View the config for an existing case
crocodash dump --caseroot ~/croc_cases/mycase

# Save it to a file and edit before re-creating
crocodash dump --caseroot ~/croc_cases/mycase > mycase_copy.yaml
# ... edit paths, dates, machine, etc. ...
crocodash create --config mycase_copy.yaml --override

The dumped YAML uses supergrid_path/from_file references pointing at the existing grid/topo/vgrid files. To create a fully independent copy, either update those paths or re-generate the grid from parameters.

crocodash bundle, fork, duplicate#

For sharing cases with others, see Shareable Configuration.

Contents