CUPID Overview
While the CUPiD environments install, let’s talk about how CUPiD works. CUPiD can provide diagnostics for a single run, or compare a single run to a single baseline run. Future development will enable comparison of more than two different runs, but the next exercise in this tutorial will be using CUPiD to create diagnostics comparing two CTSM cases that have already been run. This will be done by running the cupid-diagnostics command from the (cupid-infrastructure) environment.
(cupid-infrastructure) $ cupid-diagnostics --help
Usage: cupid-diagnostics [OPTIONS] [CONFIG_PATH]
Main engine to set up running all the notebooks.
Args: CONFIG_PATH: str, path to configuration file (default config.yml)
Returns: None
Called by ``cupid-diagnostics``.
Options:
-s, --serial Do not use LocalCluster objects
-atm, --atmosphere Run atmosphere component diagnostics
-ocn, --ocean Run ocean component diagnostics
-lnd, --land Run land component diagnostics
-ice, --seaice Run sea ice component diagnostics
-glc, --landice Run land ice component diagnostics
-rof, --river-runoff Run river runoff component diagnostics
-h, --help Show this message and exit.
Notice that cupid-diagnostics has a few options to allow you to run a subset of the default diagnostics, but the CONFIG_PATH argument (which defaults to config.yml) is the important argument. CUPiD provides a set of examples (found in the examples/ directory), each with its own config.yml file.
The Configuration File page of the CUPiD website goes into more detail looking at the key_metrics example, but in this tutorial we will look at the config.yml file associated with the land_only example.
Note that land_only provides two different configuration files (config_subset.yml and config_full.yml); we will create a softlink named config.yml that points to the subset version so we will only run a smaller portion of the diagnostics.
Before we dive into the details of how CUPiD works, let’s take a broader view of the CUPiD directory structure. As you can see in the CUPiD github repository, CUPiD has a bunch of subdirectories. For this walkthrough, we’ll talk about on just four of them:
This is the guts of the CUPiD python package that is installed in (cupid-infrastructure) (e.g. cupid-diagnostics runs cupid/run_diagnostics.py). Some of the more complex scripts are broken across multiple files: cupid-timeseries runs cupid/run_timeseries.py, which imports functions from cupid/timeseries.py.
The environments/ directory contains conda environment files for three different environments. You are currently installing two of them:
environments/cupid-infrastructure.yml: builds (cupid-infrastructure), which provides the actual CUPiD functions, and
environments/cupid-analysis.yml: builds (cupid-analysis), which provides an environment for CUPiD to use to run diagnostics notebooks.
There is also
environments/docs.yml, which builds (cupid-docs) (used to create the CUPiD website). It is not needed for most CUPiD users.
The examples/ directory contains subdirectories, each with its own config.yml file:
The directory names give a hint as to what the configuration file will provide:
key_metrics/ is the workhorse example; it aims to give a brief summary of a fully coupled CESM run (and comparisons to a baseline case).
additional_metrics/ goes into more detail than key_metrics. As you might imagine, it takes longer to run.
external_diag_packages/ pulls some key tables and figures from the output of the AMWG Diagnostic Framework (ADF), the land equivalent (LDF), and the International Land Model Benchmarking (ILAMB) project, and also links to the full output of those packages. Note that cupid-diagnostics does not run those packages directly, it expects the user to do so manually.
regional_ocean/ contains four notebooks that look at output from a regional MOM6 CESM case.
intermediary_outputs/ contains some notebooks useful to look at while deciding whether to continue a CESM case you are running (just a quick check at a few diagnostics to see if the run has gone off the rails)
land_only/ contains the LDF and ILAMB notebooks to be used when running CTSM cases.
Spoiler alert: you’ll learn a lot more about land_only on the next page.
CUPiD curates a library of notebooks that can be run by cupid-diagnostics if the config.yml file requests it. It contains subdirectories for each component of CESM:
And then each subdirectory contains one or more notebooks. For example, the lnd/ directory has:
Spoiler alert: you’re going to run LDF and ILAMB, and then CUPiD will run the LDF and ILAMB notebooks to link the webpages together.
If you want to create your own diagnostic notebook, you would add it to the repository in the appropriate subdirectory.
At this point, mamba will hopefully be done creating your environments; we'll wait for everyone to get to that point. In the meantime, if you aren't familiar with a CTSM checkout you can use Linux commands to explore the directory structure. Look at the README and other files to assess what's there.
conda activate cupid-infrastructureIf you get an error that looks something like "Shell not initialized", you'll need to install mamba for bash.
conda shell init --shell bash
conda activate cupid-infrastructureNow test that cupid-diagnostics is available for you
which cupid-diagnosticsYou'll see a path to the executable that looks something like /glade/work/$USER/conda-envs/cupid-infrastructure/bin/cupid-diagnostics.
You've cloned CTSM enabled with CUPiD and created the conda environments and made sure you can use them. Let's learn a bit about CUPID before you start your analyses!
Next running Land Diagnostics Framework (LDF) and ILAMB in CUPiD
Back to the Main LMWG-CUPiD Tutorial Page
