Walk a directory tree and return all CESM case directories found.

A directory is identified as a CESM case if it contains a CaseStatus file. Returns a newline-separated list of absolute paths.

Return the full build/run/submit status of a CESM case.

Reads the CaseStatus log and env_build.xml to report what steps are complete.

Verify that all required input data files are staged for this CESM case.

Runs ./check_input_data from the case directory and returns the output. This will report any missing files that need to be downloaded before the run.

Run ./case.setup for a CESM case.

Generates namelists, batch scripts, and env_mach_specific.xml. Pass clean=True to run './case.setup --clean'. Pass container= to run inside a crocontainer session (see start_container). Must be run before case_build.

Compile a CESM case (./case.build).

Pass container= to compile inside a crocontainer session — this is the recommended path for fast iteration since it avoids queue wait times and uses the pre-installed compilers and MPI in the container.

On Derecho without a container this can take 10–30 minutes in a batch job. Inside crocontainer it runs interactively and returns immediately on completion.

Submit a CESM case (./case.submit).

Pass container= to run inside a crocontainer session. When using a container, also pass no_batch=True — the container runs interactively and does not have access to PBS/slurm, so batch submission will fail.

container + no_batch=True is the fast-iteration path: model runs synchronously inside the container and returns output to this session with no queue wait.

Query a CESM XML configuration variable.

Runs ./xmlquery from the case directory and returns the value. Variable names are case-sensitive (e.g., STOP_N, RUN_STARTDATE, NTASKS_OCN). Pass variable='--listall' to list every defined variable.

Change a CESM XML configuration variable.

Runs ./xmlchange = from the case directory. Example: variable='STOP_N', value='5' sets the run length to 5 time units. Use xmlquery first to confirm the current value before changing.

Preview what a CESM run will look like without actually submitting.

Runs ./preview_run which shows the PE layout, estimated memory, wallclock, and the batch submission script that would be used. Useful for validating resource settings before committing to case_submit.

Return the most recent lines from a CESM run log.

Searches the case directory and its run/ subdirectory for log files. component: one of 'cesm', 'ocn', 'atm', 'ice', 'rof', or 'all' to show all logs found. Returns the last lines of the most recently modified matching log.

Check the PBS/slurm batch queue status for the most recent job submitted from this case.

Reads the CaseStatus log to extract the job ID, then queries the scheduler. Returns job state (R=running, Q=queued, C=complete, F=failed) and resource usage.

List available compsets in a CESM installation.

cesmroot: path to the CESM installation (e.g. ~/work/installs/cesm3_maddd_new) filter: optional substring to filter compset names (e.g. 'MOM6', 'NYF', 'JRA')

Uses the CIME query_config script. Returns long-name compsets and their aliases.

Build the Apptainer writable sandbox from the crocontainer registry image.

This is a one-time setup step required on Derecho before start_container can be used. Takes ~1 hour on a compute node. Submits via qcmd if queue_walltime is set.

sandbox_dir: where to create the sandbox (default: ~/scratch/crocontainer_sandbox). queue_walltime: PBS walltime for the build job (default 3h).

Start a persistent container session for interactive CESM runs.

On Derecho (Apptainer):

• sandbox_or_image: path to the writable sandbox directory. Defaults to ~/scratch/crocontainer_sandbox. Build it first with build_sandbox().

• inputdata_dir: defaults to /glade/campaign/cesm/cesmdata/inputdata.

• /glade is bind-mounted transparently so all host paths work inside container.

On local (Podman):

• sandbox_or_image: container image name (default: ghcr.io/... crocontainer).

• inputdata_dir: required — path to pre-downloaded CESM inputdata.

scratch_dir: host directory for CESM output (bound to /root/cesm/scratch inside). name: name for this session (used in container_exec and stop_container).

Returns the session name on success.

Run a CIME command inside a running container session.

name: session name from start_container. case_dir: absolute path to the CESM case directory on the host. On Derecho this path is identical inside the container (/glade is mounted). On Podman, this dir is passed as -v and mounted at the same path. command: shell command to run (e.g. './case.build', './case.submit --no-batch').

Returns the full stdout+stderr from the command.

Stop and clean up a container session started with start_container.

name: session name passed to start_container.

List running crocontainer sessions.

Shows active Apptainer instances or Podman containers by name.