Overview: x4c as a CESM Diagnostic System

Overview: `x4c` as a CESM Diagnostic System#

x4c provides a high-level diagnositc system for CESM output analysis and visualization. In this tutorial, we show some simple examples to give a quick glance of the major features, including:

The Timeseries case system
The spell magics
Adding new diagnostic variables

More detailed explainations of each feature can be found in later sections.

Example Datasets: Zhu, F. & Zhu, J. Long simulations of the Miocene Climatic Optimum, DOI: 10.5065/3QFN-GN70 (2025). https://rda.ucar.edu/datasets/d010026/.

[1]:

%load_ext autoreload
%autoreload 2

import os
os.chdir('/glade/u/home/fengzhu/Github/x4c/docsrc/notebooks')
import x4c
print(x4c.__version__)

2025.10.13

[7]:

dirpath = '/glade/campaign/cesm/development/cross-wg/diagnostic_framework/x4c/timeseries/b.e30_beta06.B1850C_LTso.ne30_t232_wgx3.192.wrkflw.1_32'
case = x4c.Timeseries(
    dirpath,
    casename='b.e30_beta06.B1850C_LTso.ne30_t232_wgx3.192.wrkflw.1',
    grid_dict={'atm': 'ne30gp3'},
)

>>> case.root_dir: /glade/campaign/cesm/development/cross-wg/diagnostic_framework/x4c/timeseries/b.e30_beta06.B1850C_LTso.ne30_t232_wgx3.192.wrkflw.1_32
>>> case.path_pattern: comp/proc/tseries/*/casename.hstr.vn.timespan.nc
>>> case.grid_dict: {'atm': 'ne30gp3', 'ocn': 'g16', 'lnd': 'ne30gp3', 'rof': 'ne30gp3', 'ice': 'g16'}
>>> case.casename: b.e30_beta06.B1850C_LTso.ne30_t232_wgx3.192.wrkflw.1
>>> case.paths["atm"]["cam.h0a"] created
>>> case.paths["atm"]["cam.h2a"] created
>>> case.paths["atm"]["cam.h1a"] created
>>> case.paths["ocn"]["mom6.h.sfc"] created
>>> case.paths["ocn"]["mom6.h.z"] created
>>> case.paths["ocn"]["mom6"] created
>>> case.paths["ocn"]["mom6.h.rho2"] created
>>> case.paths["ocn"]["mom6.h.native"] created
>>> case.paths["lnd"]["clm2.h0"] created
>>> case.paths["rof"]["mosart.h0"] created
>>> case.paths["ice"]["cice.h"] created
>>> case.paths["ice"]["cice.h1"] created
>>> case.vns["atm"]["cam.h0a"] created
>>> case.vns["atm"]["cam.h2a"] created
>>> case.vns["atm"]["cam.h1a"] created
>>> case.vns["ocn"]["mom6.h.sfc"] created
>>> case.vns["ocn"]["mom6.h.z"] created
>>> case.vns["ocn"]["mom6"] created
>>> case.vns["ocn"]["mom6.h.rho2"] created
>>> case.vns["ocn"]["mom6.h.native"] created
>>> case.vns["lnd"]["clm2.h0"] created
>>> case.vns["rof"]["mosart.h0"] created
>>> case.vns["ice"]["cice.h"] created
>>> case.vns["ice"]["cice.h1"] created

Notice that the same variable name could exist for multiple history strings (h-strings).

[8]:

case.load('TS')
case.ds['TS']

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[8], line 1
----> 1 case.load('TS')
      2 case.ds['TS']

File ~/Github/x4c/x4c/case.py:742, in Timeseries.load(self, vn, vtype, comp, hstr, timespan, load_idx, verbose, reload, **kws)
    740 else:
    741     if comp is None or hstr is None:
--> 742         raise ValueError(f'The input variable name belongs to multiple (comp, hstr) pairs: {found_comp_hstr}. Please specify via the argument `comp` and `hstr`.')
    744 if timespan is not None and not isinstance(timespan[0], str) and not isinstance(timespan[-1], str):
    745     timespan = utils.timespan_int2str(timespan)

ValueError: The input variable name belongs to multiple (comp, hstr) pairs: [('atm', 'cam.h0a'), ('atm', 'cam.h1a')]. Please specify via the argument `comp` and `hstr`.

In this case, we should specify the component and h-string:

[9]:

case.load('TS', comp='atm', hstr='cam.h0a')
case.ds['TS']

>>> case.ds["TS"] created

All derived variables should follow the same idea of specifying component and h-strings:

[11]:

case.load('LST', comp='atm', hstr='cam.h0a')
case.ds['LST']

>>> LST is a supported derived variable.
>>> case.ds["TS"] already loaded; to reload, run case.load("TS", ..., reload=True).
>>> case.ds["LANDFRAC"] created
>>> case.ds["LST"] created

[ ]:

Overview: x4c as a CESM Diagnostic System

Overview: x4c as a CESM Diagnostic System#

Overview: `x4c` as a CESM Diagnostic System#