Python Framework for Generating Diagnostics from CESM
CUPiD is a collaborative effort that unifies all CESM component diagnostics and provides
- Python code that
- runs in an easy-to-generate conda environment, and
- can be launched via CIME workflow or independently
- Diagnostics for single/multiple runs and single/multiple components
- Ability to call post-processing tools that other groups are working on
- An API that makes it easy to include outside code
- Ongoing support and software maintenance
To install CUPiD, you need to check out the code and then set up a few environments.
The initial examples have hard-coded paths that require you to be on casper
.
The code relies on submodules to install manage_externals
and then uses manage_externals
for a few packages that are still being developed,
so the git clone
process is a little more complicated than usual:
$ git clone --recurse-submodules https://github.com/NCAR/CUPiD.git
$ cd CUPiD
$ ./manage_externals/checkout_externals
Then build the necessary conda environments with
$ mamba env create -f environments/dev-environment.yml
$ conda activate cupid-dev
$ which cupid-run
$ mamba env create -f environments/cupid-analysis.yml
Notes:
- As of version 23.10.0,
conda
defaults to usingmamba
to solve environments. It still feels slower than runningmamba
directly, hence the recommendation to install withmamba env create
rather thanconda env create
. If you do not havemamba
installed, you can still useconda
... it will just be significantly slower. (To see what version of conda you have installed, runconda --version
.) - If
./manage_externals/checkout_externals
is not found, rungit submodule update --init
to clone the submodule. - If
which cupid-run
returned the errorwhich: no cupid-run in ($PATH)
, then please run the following:
$ conda activate cupid-dev
$ pip install -e . # installs cupid
CUPiD currently provides two examples for generating diagnostics.
To test the package out, try to run examples/coupled-model
:
$ conda activate cupid-dev
$ cd examples/coupled_model
$ cupid-run config.yml
$ cupid-build config.yml # Will build HTML from Jupyter Book
After the last step is finished, you can use Jupyter to view generated notebooks in ${CUPID_ROOT}/examples/coupled-model/computed_notebooks/quick-run
or you can copy the entire ${CUPID_ROOT}/examples/coupled-model/computed_notebooks/quick-run/_build/html
directory to your local machine and look at index.html
in a web browser.
For users running on the NCAR super computers (derecho or casper), you can visualize the web page in a browser using the FastX service. FastX requires you to be on the internal NCAR network (either on-site or via the VPN, and can be accessed via the following steps:
- Open a new browser window that points to https://fastx.ucar.edu:3300/session/
- Open a default desktop icon.
- Select the browser client.
- Type
xterm
and hit enter to open a terminal. - In the terminal, run
cd ${CUPID_ROOT}/examples/coupled_model/computed_notebooks/quick-run/_build/html
to enter thehtml
directory. - From the updated directory, run
firefox index.html &
to open a web browser pointed at the generated web page.